Get other documents related to an individual document

get/documents/{entityTypeName}/{documentId}/{relationshipTypeName}
Internal-Use Only

For a given document and relationship type name, finds all the documents that are related to the given document according to the given relationship type.

Since the child documents of a top-level document are related to it by a special kind of relationship type, this endpoint can be used to fetch children of a document. In this case, the name of the relationship type is identical to the child entity type, so use the child entity type name as the relationshipTypeName path parameter.

The related documents can be filtered by a date range using the date and time fields on the related document's entity type.

For the purpose of this documentation, it is important to clarify that there are two entity types to consider: the entity type that is specified in the path and the related entity type that is returned. Distinguishing between the two is important when filtering by a date range.

For example, assume there is a relationship type defined between an entity type named "entityTypeA" and another entity type named "entityTypeB" that is called "fromAToB". For the request GET /documents/entityTypeA/{documentId}/fromAtoB, "entityTypeB" is the related entity type and a collection of "entityTypeB" documents are returned.

The number of related documents can be filtered by fields on the related entity type using a combination of the "earliestValidFrom", "latestValidFrom", "earliestValidTo", "latestValidTo", "dateFieldName", "earliestDate", and "latestDate" parameters. Each of these parameters refer to a Date, Timestamp, or Timestamp With Time Zone field on the related entity type.

When using the "earliestValidFrom" and "latestValidFrom" parameters, the results are filtered by the field name that is specified in the "validFromFieldName" property in the related entity type.

When using the "earliestValidTo" and "latestValidTo" parameters, the results are filtered by the field name that is specified in the "validToFieldName" property in the related entity type.

The "dateFieldName" parameter is used to specify an arbitrary Date, Timestamp, or Timestamp With Time Zone field name on the related entity type. When specified, include "earliestDate", "latestDate", or both parameters.

Request Samples

1

Response Samples

1{
2  "links": [],
3  "name": "documents",
4  "count": 1,
5  "version": 2,
6  "items": [
7    {
8      "objectTypeName": "person",
9      "objectTypeId": 100515,
10      "objectTypeVersion": 4,
11      "id": "2f21e644-089a-47d8-a503-bbdd4d8dac3d",
12      "fieldValues": {
13        "birthday": "2020-01-05T00:00:00Z",
14        "created_at_dttm": "2020-04-13T19:17:47.84Z",
15        "created_by_user_id": "viuser",
16        "first_name": "John",
17        "id": "2f21e644-089a-47d8-a503-bbdd4d8dac3d",
18        "last_name": "Smith",
19        "last_updated_at_dttm": "2020-04-13T19:31:37.097Z",
20        "last_updated_by_user_id": "viuser",
21        "version": 4
22      },
23      "createdAt": "2020-04-13T19:17:47.840Z",
24      "lastUpdatedAt": "2020-04-13T19:31:37.097Z",
25      "validFrom": "2020-01-05T00:00:00.000Z"
26    }
27  ]
28}

Path Parameters

NameTypeRequiredDescription
documentId
string
true

The ID for the document.

entityTypeName
string
true

The name of the entity type to which the document belongs.

relationshipTypeName
string
true

The name of a relationship type that is associated with the entity type name defined in the parameter "entityTypeName".

Query Parameters

NameTypeRequiredDescription
dateFieldName
string
false

An arbitrary Date, Timestamp, or Timestamp With Time Zone field in the related entity type. If a value is provided, the field with this name is used to filter documents against the given "earliestValidFrom", "earliestValidTo", "latestValidFrom", and "latestValidTo" parameters.

earliestValidFrom
string<date-time>
false

The earliest value that is allowed for the related entity's "Valid From" date or timestamp field. If the "Valid From" field is a Date field, a date value with no timestamp is allowed. Otherwise, use an ISO-8601 timestamp value. By default, the field configured as the "validFromField" in the document's entity type is used for filtering. If the query parameter "dateFieldName" is provided, the field that is specified there overrides the entity type's configuration, and that field is used instead.

earliestValidTo
string<date-time>
false

The earliest value that is allowed for the related document's "Valid To" date or timestamp field. If the "Valid To" field is a Date field, a date value with no timestamp is allowed. Otherwise, use an ISO-8601 timestamp value. By default, the field configured as the "validToField" in the document's entity type is used for filtering. If the query parameter "dateFieldName" is provided, the field that is specified there overrides the entity type's configuration, and that field is used instead.

latestValidFrom
string<date-time>
false

The latest value that is allowed for the related document's "Valid From" date or timestamp field. If the "Valid From" field is a Date field, a date value with no timestamp is allowed. Otherwise, use an ISO-8601 timestamp value. By default, the field configured as the "validFromField" in the document's entity type is used for filtering. If the query parameter "dateFieldName" is provided, the field that is specified there overrides the entity type's configuration, and that field is used instead.

latestValidTo
string<date-time>
false

The latest value that is allowed for the related document's "Valid To" date or timestamp field. If the "Valid To" field is a Date field, a date value with no timestamp is allowed. Otherwise, use an ISO-8601 timestamp value. By default, the field configured as the "validToField" in the document's entity type is used for filtering. If the query parameter "dateFieldName" is provided, the field that is specified there overrides the entity type's configuration, and that field is used instead.

limit
integer
false

The maximum number of documents to return in this page of results. The actual number of returned documents is fewer if the collection is exhausted.

Default:
40
start
integer
false

The starting index of the first document in a page.

Default:
0

Header Parameters

NameTypeRequiredDescription
Accept-Item
string
false

The media type that the client accepts for items within the response collection.

Allowed values:
application/jsonapplication/vnd.sas.investigation.data.documentapplication/vnd.sas.investigation.data.document+jsonapplication/vnd.sas.investigation.data.masked.documentapplication/vnd.sas.investigation.data.masked.document+jsonapplication/vnd.sas.investigation.data.minimally.masked.documentapplication/vnd.sas.investigation.data.minimally.masked.document+json

Responses

StatusMeaningDescription
200OKThe request succeeded. The media type of the items inside the response collection depends on the value of the Accept-Item header in the request.Schema
404Not FoundNo documents were found that are associated with the given documents and relationship type Schema
415Unsupported Media TypeThe endpoint cannot produce collection items of the type specified in the `Accept-Item` header. Schema