Filter a collection of documents

post/documents/{entityTypeName}
Internal-Use Only

Filters a collection of documents by document ID or by using a custom filter. The type of filtering determines the media types to specify in the Content-Type header. This endpoint is a GET via POST. The reasoning for why a POST is needed is specified for each type of request.

The client can specify the type of document returned in the Accept-Item header for both types of requests. The options are:

Enriched documents are the document plus sheets (i.e, workspaces) and comments. A regular document does not include the enrichment data. Getting enriched documents is potentially less efficient than getting a document. You should use "application/vnd.sas.investigation.data.document" unless the enrichment data is required.

Specifying "application/json" in a header indicates that the client would like to use the default media type for that header. The default media types for this endpoint are:

HTTP Header Value in header Value interpreted by server
Content-Type application/json application/vnd.sas.investigation.data.document.filter.request+json
Accept application/json application/vnd.sas.collection+json
Accept-Item application/json application/vnd.sas.investigation.data.enriched.document+json

Using the default value for the Content-Type header means that the user is making a Document Filter request. Document Filter requests are requests for collections of documents that use a custom filter.

The default item type returned is an enriched document for legacy reasons.

Custom filter (Document Filter Request)

Filter a collection of documents given the type and a filter string. This is a GET via POST request. The endpoint uses this design to keep the values used for filtering (the value of the "filter" property) from being logged.

This request must have the following header and value:

HTTP Header HTTP Header value
Content-Type application/vnd.sas.investigation.data.document.filter.request+json

The body of the request will be a Document Filter Request. See the Document Filter Request model for more details.

Microsoft SQL Server and Azure SQL Server have limitations on the number of parameters that can be used when querying databases. When using this endpoint to filter documents that are stored in an SQL Server data store, large and complex filter strings that contain over 2000 parameters might fail. To circumvent this limitation, split your filter expression into smaller expressions and make multiple requests to this endpoint. Then, combine the results as appropriate.

Filter By ID (Document ID Request)

Request specific documents by providing an entity type name and an array of document ID values. Use this request when many documents by ID need to be requested. There is a similar document endpoint that accepts multiple "id" query parameters, but it is limited by the maximum URI size allowed. This request overcomes that limitation by placing the list of IDs in the body of a POST request.

Document ID Requests must have the following header and value:

HTTP Header HTTP Header value
Content-Type application/vnd.sas.investigation.data.document.id.request+json

The body of the request will be a Document ID Request. See the Document ID Request model for more details.

Filtering child documents is not supported.

Request Samples

1

Response Samples

1{
2  "links": [
3    {
4      "method": "POST",
5      "rel": "self",
6      "href": "/documents/person",
7      "uri": "/documents/person",
8      "type": "application/vnd.sas.collection",
9      "itemType": "application/vnd.sas.investigation.data.enriched.document",
10      "body": {
11        "start": 0,
12        "limit": 10,
13        "includeDisplayLabel": true,
14        "depth": "0",
15        "sortBy": "id",
16        "filter": "eq(first_name, 'John')"
17      }
18    },
19    {
20      "method": "GET",
21      "rel": "collection",
22      "href": "/documents/person",
23      "uri": "/documents/person",
24      "type": "application/vnd.sas.collection"
25    }
26  ],
27  "name": "documents",
28  "accept": "application/vnd.sas.investigation.data.enriched.document+json",
29  "start": 0,
30  "count": 1,
31  "items": [
32    {
33      "objectTypeName": "person",
34      "objectTypeId": 100924,
35      "objectTypeVersion": 6,
36      "id": "uuid_100",
37      "fieldValues": {
38        "created_at_dttm": "2015-10-01T18:30:03.656Z",
39        "created_by_user_id": "unit_test",
40        "first_name": "John",
41        "id": "uuid_100",
42        "last_name": "Smith",
43        "last_updated_at_dttm": "2015-10-01T18:30:03.656Z",
44        "last_updated_by_user_id": "unit_test",
45        "version": 1
46      },
47      "fieldRestrictions": {
48        "person": {
49          "ssn": {
50            "masked": {
51              "currentUserIsAuthorizedToReveal": true
52            }
53          }
54        }
55      },
56      "displayLabel": "John Smith",
57      "createdAt": "2015-10-01T18:30:03.656Z",
58      "lastUpdatedAt": "2015-10-01T18:30:03.656Z",
59      "attachmentsCount": 0
60    }
61  ],
62  "limit": 10,
63  "version": 2
64}

Path Parameters

NameTypeRequiredDescription
entityTypeName
string
true

The name of the entity type to which the document collection belongs. Child entity types are not supported.

Header Parameters

NameTypeRequiredDescription
Accept-Item
string
false

When making a request to filter documents, specifies the media type of the items returned.

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

Request Body

The parameters that are used for filtering, sorting, display labels, and the inclusion of child documents. There are two types of requests that can be made: request by ID or by using a custom filter. The default is using a custom filter. See the description for this endpoint for more details.

A request to filter a collection of documents.

NameTypeRequiredDescription
filter
string
false

A limited version of the filter syntax defined in the SAS REST reference guide is supported.

The only functions supported are "and", "or", and "eq" to reduce the possibility of full table scans.

Given the limited support for functions, only a select number of entity field types are supported:

Other considerations when crafting document filter queries:

Filter examples:

start
integer<int64>
false

The starting index of the first document in a page.

Default:
0
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:
20
depth
string
false

Supported values:

Default:
0
includeDisplayLabel
boolean
false

Generate and include the display label in the document.

Default:
false
sortBy
string
false

Sort a collection by field name. The sorting syntax is defined in the SAS REST reference guide. Only "ascending" and "descending" are supported. Sorting behavior is dependent on the type of underlying database in which the document data is stored. Because of this, there is a chance that the sorting behavior might differ between entity types. Sorting is not applied by default.

Example:
"first_name:ascending;last_name:descending"

Responses

StatusMeaningDescription
200OKThe request succeeded. Schema
400Bad RequestThe request was invalid.Schema
404Not FoundThe type of document was not found.Schema
415Unsupported Media TypeAn unsupported media type was provided.Schema