Retrieve documents

Contributors

GET /persistence/v1/service/{serviceName}/collection/{collectionName}/account/{accountId}

Retrieves documents from the specified collection for the specified service database and account. If documentId is mentioned in the query, that document is fetched. The documents are retuned inside an array to the user, where the user supplied persistence information is found under the document key of each element of the array. If the user queries for a single document, an array with the specified single document is returned. If no document is found, an empty array is returned.
== URL query specification

Pagination

By default, the offset is 0 and the limit is 20. You can specify any one or both of these values. The values are positive integer numbers or 0 for offset and 1 for limit. However, no check is performed for the viability of these numbers (you can specify a floating-point number).

Example:

  • GET /endpoint?offset=M&limit=N

Cross-field queries are useful when multiple fields are searched for a value or combination of values. Whereas single-field queries only allow you to search a single field for a value, cross-field queries return rows where any field in a specified set of fields matches the query. The fields to be queried are specified in the "query_fields=" parameter. This parameter must contain a comma-delimited list of fields. The behavior is equivalent to the UNIX grep -i command, which means that the value matches anywhere in the string and is not case sensitive.

Example:

  • GET /endpoint/servers?query=my_server&query_fields=server,ip,state

Single-field filtering

Represented as field=value where the value is matched only for specified field. The behavior is equivalent to the UNIX grep command, which means that the value is an exact match with the specified field and is case sensitive.

Examples:

  • GET /endpoint/servers?server=my_server

  • GET /endpoint/servers?server=my_server&ip_addr=10.10.10.10

Sorting

Represented as order_by=field asc/desc. Ascending by default means that if the user only specifies order_by=field, then it returns in ascending order.
Note that the field or fields must be indexed to be sortable.

Examples:

  • GET /endpoint/servers?order_by=server desc

  • GET /endpoint/servers?order_by=server

  • GET /endpoint/servers?order_by=server asc

The last two examples are equivalent.

Total document count

If the total_documents query parameter is passed to the URL, it returns the total number of documents present in the collection after applying the filter, if any.
This query parameter does not take any value.

Examples:

  • GET /endpoint/servers?total_documents

  • GET /endpoint/servers?k3=true&offset=1&limit=1&total_documents

The last example returns the total number of documents present in the collection after applying the filter value true in field k3. However, the documents array contains only one document (offset=1&limit=1).

NOT supported

  • Regex in filtering (e.g. field=abc*)

  • Comparison in filtering (e.g. >, =, ⇐)

  • Escape character support in filtering. The special character is treated literally, without any specific meaning (for example, field="").

  • Returns only the desired field from collections or individual documents instead of returning all fields in the documents.

  • Asterisk () denotes all fields in the cross-field search (for example, query_fields=). This means global string search is not supported.

Parameters

Name Type In Required Description

_id

string

query

False

Document identifier specified in object ID format as _id or documentId.

documentId

string

query

False

Document identifier specified in object ID format as documentId or _id.

offset

number

query

False

Number of records to be skipped to retrieve the documents. Default is 0, starts from 0.

limit

number

query

False

Batch size. Number of documents to be fetched in a single API call. Default is 20. Minimum is 1.

order_by

string

query

False

Sorting specifier. Specifies which field to sort: order_by=asc/desc

query_fields

string

query

False

Comma separated, cross-field query keys specifier. Identifies the document keys to be queried for the given value in the query.

query

string

query

False

Cross-field query value specifier. Value searched across the specified keys in query_fields.

total_documents

string

query

False

Total number of documents present in the collection, after applying filters, if any. Example: /endpoint?total_documents

serviceName

string

path

True

Participating external service name (name of the database).

collectionName

string

path

True

Persistence service collection name (name of the table).

accountId

string

path

True

Persistence Service Cloud Manager account identifier for Tenancy service specification.

X-Service-Request-Id

string

header

False

Request identifier used to tag the request for better supportability.

Response

Status: 200, Default response
Name Type Required Description

documents

array[PersistenceServiceResponse]

False

All the retrieved documents from the specified collection for the specified database and account.

total_documents

number

False

If total_documents query paremeter is specified, it displays the total number of documents present in the collection after applying query paramaters, if any. If total_documents is not specified, it returns -1.

Response

Status: 4xx, Error response.
Name Type Required Description

errorCode

string

False

Error code

error

string

False

Error category

message

string

False

Error description message

Example response

{
  "errorCode": "P1002",
  "error": "api error",
  "message": "No document found of the specified documentId"
}

Definitions

PersistenceServiceRequest

(Opaque) Persistence service document as a key-value pair passed as a request.

PersistenceServiceResponse

Persistence Service response document.

Name Type Required Description

_id

string

False

Persistence Service response document identifier. Auto generated and immutable.

document

PersistenceServiceRequest

False

(Opaque) Persistence service document as a key-value pair passed as a request.