Data Document

A data document is the straightforward JSON representation of all the Entities in a Dataset.

The $top and $skip querystring parameters, specified by OData, apply limit and offset operations to the data, respectively. The $count parameter, also an OData standard, will annotate the response data with the total row count, regardless of the scoping requested by $top and $skip. If $top parameter is provided in the request then the response will include @odata.nextLink that you can use as is to fetch the next set of data. As of ODK Central v2023.4, @odata.nextLink contains a $skiptoken (an opaque cursor) to better paginate around deleted Entities.

The $filter querystring parameter can be used to filter certain data fields in the system-level schema, but not the Dataset properties. The operators lt, le, eq, ne, ge, gt, not, and, and or are supported. The built-in functions now, year, month, day, hour, minute, second are supported.

The fields you can query against are as follows:

Note that createdAt, updatedAt and deletedAt are time components. This means that any comparisons you make need to account for the full time of the entity. It might seem like $filter=__system/createdAt le 2020-01-31 would return all results on or before 31 Jan 2020, but in fact only entities made before midnight of that day would be accepted. To include all of the month of January, you need to filter by either $filter=__system/createdAt lt 2020-02-01T00:00:00.000Z or $filter=__system/createdAt lt 2020-02-01. Remember also that you can query by a specific timezone.

Please see the OData documentation on $filter operations and functions for more information.

The $select query parameter will return just the fields you specify and is supported on __id, __system, __system/creatorId, __system/createdAt and __system/updatedAt, as well as on user defined properties.

The $orderby query parameter will return Entities sorted by different fields, which come from the same list used by $filter, as noted above. The order can be specified as ASC (ascending) or DESC (descending), which are case-insensitive. Multiple sort expressions can be used together, separated by commas, e.g. $orderby=__system/creatorId ASC, __system/conflict DESC.

The $search query parameter can be used to search entity data (user-defined properties) and the label field. Central does not implement the OData specification's suggested search techniques—such as AND, NOT, and parentheses grouping—exactly as described. Instead, the search behavior is similar to that of a web search engine:

• Multiple words return entities that contain all the searched words (logical AND operation).
• The OR keyword can be used to find entities that contain any of the searched words.
• Quoted text (e.g., "quoted text") searches for entities containing the exact phrase.
• A dash (-) before a word excludes entities that contain that word (logical NOT).

The viewAs query parameter can be used to preview what a specific Actor would receive, based on the Dataset's access filter (ownerOnly or property rules). Pass a numeric Actor ID as the value. This is intended to preview what an App User or Public Link would see when fetching these Entities as a Form Attachment. This parameter can be combined with other filters, e.g. to see the subset of an Actor's Entities that also match a given $filter or $search expression.

As the vast majority of clients only support the JSON OData format, that is the only format ODK Central offers.