Accessing Data Records

Overview

FEDERATED Data records reside on systems connected to YOUnite with an adaptor. YOUnite catalogs FEDERATED data records and stores metadata but does NOT store the actual data for these records.

`FEDERATED` Data Records

As data events flow through YOUnite for FEDERATED domain versions, metadata is stored for each Data Record including:

The date/time the data records was created
The DR Key Properties
The adaptor(s) that have a linkage of the data record
The actual data of FEDERATED Data Records is NOT stored in YOUnite. Only the DR Key Properties are stored.

Retrieving Data Record Metadata

Metadata for data records can be retrieved via the YOUnite Server’s APIs.

To retrieve data for FEDERATED data records see Assembling Federated Data Records below.

Retrieve all records

To retrieve a list of data records (DRs) for a given domain using the default version:

GET /drs?filters=name:domain-name

To retrieve a list of data records (DRs) for a given domain using a specific version:

GET /drs?filters=name:<domain-name>,version:<version-number>

FEDERATED example (does NOT include the actual data of the data record):

GET /drs?filters=name:customer&page=0&size=2

Response:

{
    "drs": [
        {
            "uuid": "0043c03e-7622-4a7c-b448-313a9e73bd9c",
            "adaptorUuid": "cadcd847-a7fd-485c-b0a7-4f1a186e27c4",
            "domainVersionUuid": "a424ab23-eaa1-44f3-811e-f32b89a11e2a",
            "dateCreated": 1649793665529,
            "drKey": {
                "customerId": "GAV1525741"
            }
        },
        {
            "uuid": "0043c03e-7622-4a7c-b448-313a9e73bd9c",
            "adaptorUuid": "e681f80f-9972-4548-a505-6e8eb99d5d0c",
            "domainVersionUuid": "a424ab23-eaa1-44f3-811e-f32b89a11e2a",
            "dateCreated": 1649793671149,
            "drKey": {
                "customerId": "GAV1525741"
            }
        }
    ],
    "_links": {
        "first": "http://locahost:8080/api/drs?filters=name%3Acustomer&page=0&size=2",
        "last": "http://locahost:8080/api/drs?filters=name%3Acustomer&page=2999&size=2",
        "self": "http://locahost:8080/api/drs?filters=name%3Acustomer&page=0&size=2",
        "next": "http://locahost:8080/api/drs?filters=name%3Acustomer&page=1&size=2"
    },
    "_page": {
        "page": 0,
        "size": 2,
        "totalElements": 6000,
        "totalPages": 3000
    }
}

Retrieve specific records

To retrieve a list of data records (DRs) by their UUIDs, use the dr-uuids filter and put a colon (:) between each UUID:

GET /drs?filters=name:country,version:4,dr-uuids:1962212c-e438-4ebf-bb4d-0efc0d7544f0:675a5edd-56db-4e9a-b36f-aeaa093e6251

Querying and Sorting

Data Records can be queried using Lucene syntax on values of the domain version’s Data Record Key Properties. For example, if version 1 of the domain country has a DR Key property countryCode, the record for MEX can be retrieved like so:

GET /drs?filters=name:country,version:1&query=countryCode:MEX

For those domain versions that have a single DrKey property, the name of the field can be excluded:

GET /drs?filters=name:country,version:1&query=MEX

Response:

{
    "drs": [
        {
            "uuid": "c4f57e9d-8d96-4e19-831a-34c95f4b5fc2",
            "domainVersionUuid": "1de3051d-7a56-4c5c-996b-58461a0abd98",
            "createdByUuid": "da823503-20e3-4505-922a-ae2ca319ef82",
            "dateCreated": 1608768418615,
            "json": {
                "name": "Mexico",
                "countryCode": "MEX",
                "capital": "Mexico City",
                "population": 128932753
            },
            "drKey": {
                "countryCode": "MEX"
            }
        }
    ],
    "_links": {
        "first": "http://localhost:8080/api/drs?filters=name%3Acountry&query=countryCode:MEX&page=0&size=10",
        "last": "http://localhost:8080/api/drs?filters=name%3Acountry&query=countryCode:MEX&page=0&size=10",
        "self": "http://localhost:8080/api/drs?filters=name%3Acountry&query=countryCode:MEX&page=0&size=10"
    },
    "_page": {
        "page": 0,
        "size": 10,
        "totalElements": 1,
        "totalPages": 1
    }
}

If a domain version has multiple DR Key properties AND and OR can be used:

GET /drs?filters=name:state,version:1&query=countrycode:USA AND state:MA

GET /drs?filters=name:customer,version:1&query=firstName:Bob OR firstName:Steve

The wildcards asterisk (*) and question mark (?) can be used. Asterisk for zero or more characters and question mark for exactly one character.

Retrieve all countries that start with the letter "U":

GET /drs?filters=name:state,version:1&query=countryCode:U*

Retrieve all countries that have a three-character country code starting with "U":

GET /drs?filters=name:state,version:1&query=countryCode:U??

Results can be paginated with the page and size query parameters.

GET /drs?filters=name:customer,version:1&query=firstName:Bob&page=4&size=10

The results can be sorted by any DR key value. For descending order, put a minus (-) in front of the value:

GET /drs?filters=name:customer,version:1,dr-key:firstName=bob&sort=lastName,firstName

GET /drs?filters=name:state,version:1&sort=-population

If a domain version has cross-references (REFs) to other domain versions, then REF expansion can be suppressed by setting the expandRefs option to false (default value is true). Setting this to false will display only the REF property name and the drKeyProperty value used to cross-reference the domain version relationship:

GET /drs?filters=name:state,version:1&options=expandRefs:false

To get a specific DR with the expandRefs option set to false:

GET /drs/da53c1c5-945c-42fb-821f-77ea6e20302c?options=expandRefs:false

Note	Only the Data Record Key (DrKey) values and properties are returned. See Assembling Federated Data Records below for how to retrieve federated data records.

Lucene Query Examples

Data Records can be queried using Lucene syntax on values of the domain version’s Data Record Key Properties (DR Key).

Search by a single field:

lastName:Ross

Search with an OR statement:

lastName:Ross OR lastName:Geldof

Search with an AND statement:

lastName:Ross AND firstName:Bob

The NOT statement:

firstName:Bob AND NOT lastName:Geldof

Using parenthesis (also quotation marks to handle words with spaces):

(lastName:Ross AND occupation:"Television Personality") OR (lastName:Geldof AND occupation:"Rock Star")

Fuzzy matching (returns results with two or less character differences):

lastName:Geldof~

Wildcards:

lastName:R* AND firstName:B??

Range:

age:[60 TO 80]

Regular expressions - this example will match anything start with "los" and ending in "es" such as Los Angeles or Los Cruces:

city:/^los.*es$/

Lucene Feature Support

Not all Lucene features are supported. The following operations are supported:

Wildcard searches
Fuzzy searches
Range searches
Boolean operations (AND, OR, NOT, +, -)
Grouping using parenthesis
Field Grouping
Regular expressions

The following are not supported:

Proximity searches
Scoring, relevance

Note	Lucene queries in YOUnite are case insensitive

Shortcuts and Search by DR (Data Record) UUID

If a domain version has only one DR Key property, then the DR Key property name can be omitted in the search.

For example, if the "customer" version "1" domain version has only the "customerID" DR Key and there is a customer with customerID "bc359ea3"

Search can be performed without specifying the DR Key:

bc359ea3

Search for several customers by "customerID":

bc359ea3 OR d50563fa OR 59a5d85a

Search can be performed by the DR UUID by simply providing the DR’s UUID (only one DR UUID can be provided):

7916463a-00f4-4052-999c-e5cdedd8ed79

However, if a domain version has a lone DR Key that is in UUID format, then searching by the DR Key requires the DR Key property name.

For example, if "customer" version "1" has a single DR Key "customerId" that is in UUID format and there is a record with "customerId" value "c4d56cc4-c068-4e06-a632-f3e334900af0" (a UUID) and the DR UUID for this record is "17aa6934-3d88-42ef-8b8f-f4814b214441", then to search by the DR key will require the DR Key property name:

customerId:c4d56cc4-c068-4e06-a632-f3e334900af0

To search for this record by UUID would simply require the DR UUID:

17aa6934-3d88-42ef-8b8f-f4814b214441

Metadata by Adaptor

Specific properties for a data domain are designated as the Data Record Key (DrKey). They are used for:

Ensuring duplicate data records are not created in YOUnite for a given domain version
Matching data records to each other - see Matching Algorithms
Fast lookup of federated data

Each Adaptor that is linked to a Data Record will have its own DrKey. These DrKeys may differ from adaptor to adaptor when Matching Algorithms are used. When retrieving data record metadata for a federated data domain, DrKey values for each adaptor are returned unless a specific adaptor is specified as a filter option or if the exclude-adaptors filter is option is set to true.

Examples:

Querying all adaptors (will include one record per adaptor with a data record that matches the query):
```
GET /drs?filters=name:customer,version:1&query=lastName:Ross&page=0&size=8&sort=firstName
```

Querying a specific adaptor (will include one record per data record that matches the query for the given adaptor):

GET /drs?filters=name:customer,version:1,adaptor:afb24f24-0080-44aa-b656-502a56316085&query=lastName:Ross&page=0&size=8&sort=firstName

Querying without adaptor information (will include one record per data record that matches the query at one or more adaptor):
```
GET /drs?filters=name:customer,version:1,exclude-adaptors:true&query=lastName:Ross&page=0&size=8&sort=firstName
```

Check if a Data Record is Mapped at a Specific Adaptor

To check if the YOUnite Server has a link for a given data record at an adaptor:

GET /drs/<dr-uuid>/adaptor/<adaptor-uuid>/check

If the link exists a 200 OK is returned and a 404 NOT FOUND if not.

Note

It is up to the adaptor to inform YOUnite about whether data records exist on its system, so a 404 NOT FOUND is not a definitive indication of whether a record does or not exist at a data source. The "off-the-shelf" adaptors supplied by YOUnite are designed to keep an accurate record of which records are linked at which adaptors are data events flow through the system.

Assembling Federated Data Records

Retrieving Data Record Metadata and Querying and Sorting above covered how to access the metadata of FEDERATED data records. To retrieve the actual data of a FEDERATED data record, one or more adaptor(s) is queried and asked to send the data to YOUnite where the data is merged together and sent back to the user. This process is called data record assembly, or assembly for short.

Assembly is handled by a separate, optional service called the YOUnite Data Virtualization Service. This service runs independently of the YOUnite Server, although it shares the same database, and has its own set of APIs. In this section, all requests will refer to the YOUnite Data Virtualization Service APIs and not the YOUnite Server APIs. The base URL of the APIs of this service are referred to as "<dvs-url>". For example, running locally this might be http://localhost:8084/request or http://local.younite.org/request.

Note	Assembly is also sometimes referred to as a "Federated GET". When setting up governance, the `GET` method is the one that allows or restricts assembly of data records.

Restricting or Allowing Assembly with Data Governance and Adaptor Capabilities

An adaptor’s capabilities determine what types of data events it is capable of receiving. Whereas the POST, PUT and DELETE actions refer to the flow of data events, the GET action refers to assembly requests.

In addition, the ACLs that control the flow of data events to and from adaptors also control whether an adaptor can receive requests for assembly. Just like the adaptor’s capabilities, the GET action refers to assembly requests.

SDK-based Assembly Permissions

Although adaptor capabilities and data governance control whether assembly requests will be routed to a specific adaptor, adaptor software built on the YOUnite SDK may choose to acknowledge or ignore these requests.

The "off-the-shelf" YOUnite Database Adaptor includes a configuration option writeOnly which, when set to true will disable assembly at that adaptor.

User-based Assembly Permissions

Adaptor capabilities, data governance and the adaptor software itself determine whether an adaptor can receive and process assembly requests. The final layer of security is the user layer. The user security model allows fine-grained permissions by zone, adaptor, domain, domain version, properties and even specific DR UUIDs. These are the same options that can be configured with data governance / ACLs, but by user instead.

Note	User-based permissions are configured on the YOUnite Server, NOT the YOUnite Data Virtualization Service.

Configuring User Permissions

See Zones, Users, Groups, Roles, Permissions and Data Access Rules for information on assigning users to groups and/or roles. The Data Access Rules of the roles that a user has been assigned to determine what level of access a user has to search for and assemble data records.

Request Assembly of Federated Data Record(s)

Assembly of data records is handled by the optional YOUnite Data Virtualization Service. The API requests below refer to this service, with <dvs-url> being the base URL of this service, for example, http://localhost:8084/request.

Note	This service will typically use the same authentication server as the YOUnite Server.

A single endpoint, POST <dvs-url>/request handles assembly requests. See Assembly Request Options for a full list of request options.

Examples:

All data records in a domain version

POST <dvs-url>/request

{
    "domain": "customer",
    "versionNumber": 1,
    "zoneUuid": "<user-zone-uuid>",
    "timeout": 60,
    "releasePolicy": "GOLD_SILVER"
}

Specific data records at a specific adaptors by UUID

POST <dvs-url>/request

{
    "drUuids": [
      "<dr-uuid>",
      "<dr-uuid>",
      "<dr-uuid>"
    ],
    "adaptors": [
      "<adaptor-uuid>",
      "<adaptor-uuid>"
    ],
    "zoneUuid": "<user-zone-uuid>",
    "timeout": 60,
    "releasePolicy": "GOLD_SILVER"
}

Assembly Request Response

{
    "uuid": "9d07238f-2216-4810-b8bd-73b15ca7091f",
    "domain": "customer",
    "versionNumber": 1,
    "domainVersionUuid": "a424ab23-eaa1-44f3-811e-f32b89a11e2a",
    "virtualizationRequest": {
        "page": 0,
        "size": 2,
        "timeout": 60,
        "releasePolicy": "GOLD_SILVER",
        "expandRefs": false,
        "outputType": "FULL",
        "drUuids": null,
        "domain": "customer",
        "versionNumber": 1,
        "domainVersionUuid": null,
        "zoneUuid": "6aca539c-6616-46d4-8cdd-d7b3f16e523f",
        "requestedProperties": null,
        "goldAdaptors": null,
        "silverAdaptors": null,
        "bronzeAdaptors": null,
        "adaptors": null,
        "drKeys": null,
        "query": null,
        "sort": null,
        "additionalParams": null
    },
    "assembledDataRecords": [
        {
            "uuid": "007ea65c-1ff5-4ac0-9098-7590aba76420",
            "data": {
                "zip": "34479",
                "firstName": "Herta",
                "lastName": "Sheridan",
                "address": "0567 Lillian Hill",
                "phone": "352-656-4349",
                "city": "Ocala",
                "customerId": "JZV1422435",
                "state": "FL",
                "salesRepId": "8331619BNQ",
                "birthDate": "1991-02-04",
                "email": "hsheridan7f@webmd.com"
            },
            "status": "PREFERRED_COMPLETE",
            "drKey": {
                "customerId": "JZV1422435"
            },
            "adaptors": [
                {
                    "uuid": "e681f80f-9972-4548-a505-6e8eb99d5d0c",
                    "name": "Europe West Database - SQL Server",
                    "zoneUuid": "39d991f5-beba-4c6c-9894-03e55cdd69fe",
                    "zoneName": "Europe Headquarters",
                    "additionalParams": null
                }
            ]
        },
        {
            "uuid": "0043c03e-7622-4a7c-b448-313a9e73bd9c",
            "data": {
                "zip": "46896",
                "firstName": "Tana",
                "lastName": "Lefridge",
                "address": "06 Vahlen Plaza",
                "phone": "260-801-0914",
                "city": "Fort Wayne",
                "customerId": "GAV1525741",
                "state": "IN",
                "salesRepId": "0516870LVW",
                "birthDate": "1934-09-19",
                "email": "tlefridge6d@booking.com"
            },
            "status": "PREFERRED_COMPLETE",
            "drKey": {
                "customerId": "GAV1525741"
            },
            "adaptors": [
                {
                    "uuid": "e681f80f-9972-4548-a505-6e8eb99d5d0c",
                    "name": "Europe West Database - SQL Server",
                    "zoneUuid": "39d991f5-beba-4c6c-9894-03e55cdd69fe",
                    "zoneName": "Europe Headquarters",
                    "additionalParams": null
                }
            ]
        }
    ],
    "_page": {
        "page": 0,
        "size": 2,
        "totalElements": 1000,
        "totalPages": 500
    },
    "schemaEntries": [
        {
            "name": "customerId",
            "propertyType": "STRING"
        },
        {
            "name": "firstName",
            "propertyType": "STRING"
        },
        {
            "name": "lastName",
            "propertyType": "STRING"
        },
        {
            "name": "email",
            "propertyType": "STRING"
        },
        {
            "name": "birthDate",
            "propertyType": "STRING"
        },
        {
            "name": "phone",
            "propertyType": "STRING"
        },
        {
            "name": "address",
            "propertyType": "STRING"
        },
        {
            "name": "city",
            "propertyType": "STRING"
        },
        {
            "name": "state",
            "propertyType": "STRING"
        },
        {
            "name": "zip",
            "propertyType": "STRING"
        },
        {
            "name": "salesRepId",
            "propertyType": "STRING"
        }
    ]
}

Assembly Request Options

Property	Description	Default	Required
zoneUuid	UUID of the zone that the authenticated user belongs to that is requesting the data. Required unless the user is only part of a single zone.		Yes unless user is only in one zone
domain	If querying by DR Key or for all records this is REQUIRED and is the name of the domain the DR Key belongs to. Otherwise ignored.		Yes if querying by DR Key or for all records
versionNumber	If querying by DR Key or for all records this is OPTIONAL and is the version of the domain (defaults to 1). Otherwise ignored.	1	Optional if querying by DR Key or for all records
timeout	Number of seconds to wait for responses from adaptors before returning a result. If time expires, the response may be incomplete.	30 seconds	No
releasePolicy	The policy to determine which adaptors are "preferred". Options are GOLD, GOLD_SILVER or ASAP.	GOLD_SILVER	No
expandRefs	Expand cross-references by assembling them as well.	false	No
maxRefSize	Limits the number of cross-referenced that may be retrieved, per cross-reference. Applicable to multivalued cross-references only.	10	No
maxRefDepth	Limits the maximum depth of cross-references in the final result. For example, a value of 1 would include the parent record and its child records. A value of 2 would include the parent record, child records and grandchild records, etc.	10	No
requestedProperties	List of properties to request from the adaptors.	All properties	No
adaptors	List of adaptors to query by UUID.	All capable adaptors	No
goldAdaptors	List of adaptors by UUID to consider "gold" for this request, even if they would not typically be considered gold.		No
silverAdaptors	List of adaptors by UUID to consider "silver" for this request, even if they would not typically be considered silver.		No
bronzeAdaptors	List of adaptors by UUID to consider "bronze" for this request, even if they would not typically be considered bronze.		No
drUuids	List of Data Record UUIDs to retrieve.	All Data Records in the domain	No
drKeys	List of Data Record DR Keys to retrieve.	All Data Records in the domain	No
query	Lucene-style query. May only query on DR Key properties of the domain version. See Querying and Sorting.		No
sort	Sort. May only sort on DR Key properties of the domain version. See Querying and Sorting.		No
page	Page number to retrieve, starting at 0.	0	No
size	Page size.	10	No
additionalParams	Additional parameters in the request to be passed to the adaptors.		No

Property

Description

Default

Required

zoneUuid

UUID of the zone that the authenticated user belongs to that is requesting the data. Required unless the user is only part of a single zone.

Yes unless user is only in one zone

domain

If querying by DR Key or for all records this is REQUIRED and is the name of the domain the DR Key belongs to. Otherwise ignored.

Yes if querying by DR Key or for all records

versionNumber

If querying by DR Key or for all records this is OPTIONAL and is the version of the domain (defaults to 1). Otherwise ignored.

Optional if querying by DR Key or for all records

timeout

Number of seconds to wait for responses from adaptors before returning a result. If time expires, the response may be incomplete.

30 seconds

releasePolicy

The policy to determine which adaptors are "preferred". Options are GOLD, GOLD_SILVER or ASAP.

GOLD_SILVER

expandRefs

Expand cross-references by assembling them as well.

false

maxRefSize

Limits the number of cross-referenced that may be retrieved, per cross-reference. Applicable to multivalued cross-references only.

maxRefDepth

Limits the maximum depth of cross-references in the final result. For example, a value of 1 would include the parent record and its child records. A value of 2 would include the parent record, child records and grandchild records, etc.

requestedProperties

List of properties to request from the adaptors.

All properties

adaptors

List of adaptors to query by UUID.

All capable adaptors

goldAdaptors

List of adaptors by UUID to consider "gold" for this request, even if they would not typically be considered gold.

silverAdaptors

List of adaptors by UUID to consider "silver" for this request, even if they would not typically be considered silver.

bronzeAdaptors

List of adaptors by UUID to consider "bronze" for this request, even if they would not typically be considered bronze.

drUuids

List of Data Record UUIDs to retrieve.

All Data Records in the domain

drKeys

List of Data Record DR Keys to retrieve.

All Data Records in the domain

query

Lucene-style query. May only query on DR Key properties of the domain version. See Querying and Sorting.

sort

Sort. May only sort on DR Key properties of the domain version. See Querying and Sorting.

page

Page number to retrieve, starting at 0.

size

Page size.

additionalParams

Additional parameters in the request to be passed to the adaptors.

Note

If adaptors are explicitly requested via adaptors, goldAdaptors, silverAdaptors or bronzeAdaptors then only those adaptors will be queried, regardless of which option is used. If none of these options are used, all adaptors capable of GET for the domain version will be queried. Finally, those requested or capable adaptors will then be filtered through ACLs and user permissions to determine which adaptors are actually queried.

Gold/Silver/Bronze Adaptors

The zone data steward or the API consumer can specify gold and silver adaptors.

To query specific adaptors using the zone’s default gold and silver priorities, put the adaptor UUID(s) in adaptors like so:

POST <dvs-url>/request

{
    "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3",
    "drUuids": [
      "a7d5744b-fd26-4eb2-b6cb-561c09005667"
    ],
    "adaptors": [
      "c0e7305c-67bc-488a-959e-b1d811633c11",
      "1dc1fae7-e369-477d-8425-79b0d5d4d88a",
      "15d41b42-8ca8-4622-bc87-439eb97f6918"
    ]
}

To override the zone’s default gold and silver adaptors, put the adaptor UUIDs in goldAdaptors, silverAdaptors, bronzeAdaptors like so:

POST <dvs-url>/request

{
    "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3",
    "drUuids": [
      "a7d5744b-fd26-4eb2-b6cb-561c09005667"
    ],
    "goldAdaptors": [
      "c0e7305c-67bc-488a-959e-b1d811633c11"
    ],
    "silverAdaptors": [
      "1dc1fae7-e369-477d-8425-79b0d5d4d88a"
    ],
    "bronzeAdaptors": [
      "15d41b42-8ca8-4622-bc87-439eb97f6918"
    ]
}

More can be found on the Gold and Silver Adaptors page.

Temporal Adaptor Assembly

The optional YOUnite Temporal Adaptor stores snapshots of data records at a point in time. Temporal adaptors have a few extra parameters that can be used to leverage the features of the temporal adaptor. These values are passed in additionalParams in the POST request:

parameter	Description	Example
timestamp	Assemble the record as of a point in time. Can be expressed as an epoch timestamp in milliseconds or in ISO-8601 format with time zone.	1617038624000 or 2021-03-29T10:23:44-07:00
timestamp-search	Instead of assembling a data record, return a list of timestamps for that data record. Passing in "true" to do this search.	true
timestamp-start	When doing a timestamp search, indicate a starting timestamp for the search	1617038624000 or 2021-03-29T10:23:44-07:00
timestamp-end	When doing a timestamp search, indicate an ending timestamp for the search	1617038624000 or 2021-03-29T10:23:44-07:00
timestamp-ascending	True or false indicating whether to sort timestamps in ascending order. The default is true.	true or false
timestamp-max	Maximum number of timestamps to return. By default there is no maximum (all are returned that meet the other criteria).	100
source-adaptor	Filter to only retrieve data events (or timestamps if searching) that originated from a specific adaptor, by UUID.	d4975612-d022-4584-8100-a014c02830ac

parameter

Description

Example

timestamp

Assemble the record as of a point in time. Can be expressed as an epoch timestamp in milliseconds or in ISO-8601 format with time zone.

1617038624000 or 2021-03-29T10:23:44-07:00

timestamp-search

Instead of assembling a data record, return a list of timestamps for that data record. Passing in "true" to do this search.

true

timestamp-start

When doing a timestamp search, indicate a starting timestamp for the search

1617038624000 or 2021-03-29T10:23:44-07:00

timestamp-end

When doing a timestamp search, indicate an ending timestamp for the search

1617038624000 or 2021-03-29T10:23:44-07:00

timestamp-ascending

True or false indicating whether to sort timestamps in ascending order. The default is true.

true or false

timestamp-max

Maximum number of timestamps to return. By default there is no maximum (all are returned that meet the other criteria).

100

source-adaptor

Filter to only retrieve data events (or timestamps if searching) that originated from a specific adaptor, by UUID.

d4975612-d022-4584-8100-a014c02830ac

Example - querying one temporal adaptor by timestamp:

POST <dvs-url>/request (timestamp in epoch milliseconds)

{
    "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3",
    "drUuids": [
      "a7d5744b-fd26-4eb2-b6cb-561c09005667"
    ],
    "adaptors": [
      "c0e7305c-67bc-488a-959e-b1d811633c11"
    ],
    "additionalParams": {
      "timestamp": 1617038624000
    }
}

POST <dvs-url>/request (timestamp in ISO-8601 format with time)

{
    "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3",
    "drUuids": [
      "a7d5744b-fd26-4eb2-b6cb-561c09005667"
    ],
    "adaptors": [
      "c0e7305c-67bc-488a-959e-b1d811633c11"
    ],
    "additionalParams": {
      "timestamp": "2021-03-29T10:23:44-07:00"
    }
}

Example - searching for timestamps in a range:

POST <dvs-url>/request

{
    "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3",
    "drUuids": [
      "a7d5744b-fd26-4eb2-b6cb-561c09005667"
    ],
    "adaptors": [
      "c0e7305c-67bc-488a-959e-b1d811633c11"
    ],
    "additionalParams": {
      "timestamp-search": true,
      "timestamp-start" :1617010204000,
      "timestamp-end" :1617038624000,
      "timestamp-max" :100,
      "timestamp-ascending" :false
    }
}

Example - searching for timestamps with source adaptor filter:

POST <dvs-url>/request

{
    "zoneUuid": "6c5a754b-6ce0-4871-8dec-d39e255eccc3",
    "drUuids": [
      "a7d5744b-fd26-4eb2-b6cb-561c09005667"
    ],
    "adaptors": [
      "c0e7305c-67bc-488a-959e-b1d811633c11"
    ],
    "additionalParams": {
      "timestamp-search": true,
      "source-adaptor": "d4975612-d022-4584-8100-a014c02830ac"
    }
}

Notes:

Typically temporal data record assembly would only be done on a single adaptor at a time, or at the very least, only on temporal adaptors, otherwise the result may combine data from different points in time.
Timestamp searching should only be done on a single adaptor at a time.

Expanding Cross-references

When expandRefs is set to true, cross-referenced records are assembled in addition to the requested record, and included in the result. The cross-reference is assembled using the same parameters as the rest of the request, ie it will use the same requested adaptors and gold / silver preferences.

Notes:

To ensure a cross-reference is expanded, it must be in the list of requested-properties
Filtering properties in the cross-referenced record is not supported

See Cross Domains for more information

Accessing Data Records

Overview

FEDERATED Data Records

Retrieving Data Record Metadata

Retrieve all records

Retrieve specific records

Querying and Sorting

Lucene Query Examples

Lucene Feature Support

Shortcuts and Search by DR (Data Record) UUID

Metadata by Adaptor

Check if a Data Record is Mapped at a Specific Adaptor

Assembling Federated Data Records

Restricting or Allowing Assembly with Data Governance and Adaptor Capabilities

SDK-based Assembly Permissions

User-based Assembly Permissions

Configuring User Permissions

Request Assembly of Federated Data Record(s)

Assembly Request Response

Assembly Request Options

Gold/Silver/Bronze Adaptors

Temporal Adaptor Assembly

Expanding Cross-references

`FEDERATED` Data Records