Find documents (HTTP)

For details about additional languages, see:

Finds documents in a collection using filter and sort clauses, including vector search.

If you add or remove documents after starting the operation, the result might not reflect real-time changes in the data.

Ready to write code? See the examples for this method to get started.

Result

The response includes a data.documents property, which is an array of objects representing documents that match the specified filter and sort clauses.

The fields included in the returned documents depend on the subset of fields that were requested in the projection. If requested and applicable, each document will also include a $similarity key with a numeric similarity score that represents the closeness of the sort vector and the document’s vector.

If the query supports pagination, the response also includes a data.nextPageState property, which indicates the ID of the next page of results, if any. For non-vector searches, the results will be paginated if more than 20 documents match the specified filter and sort clauses. For details about iteration, see Iterate over found documents.

For vector search, returns a single page of up to 1000 documents (or a lower amount if specified) instead of a cursor.

If requested when executing a vector search, the result also includes a status.sortVector property, which is the sort vector used for the search.

Example response:

{
  "data": {
    "documents":[
      {
        "_id":"85a54382-9227-4075-a543-829227407556",
        "title":"Within Silence of the Past",
        "is_checked_out":false
      },
      {
        "_id":"aa762475-4fc1-4477-b624-754fc1f477c7",
        "title":"Beyond Dreams and Forgotten Worlds",
        "is_checked_out":false
      }
    ],
    "nextPageState":"LQAAAAEBAAAAJGQ2OTk5NzY2LTgyODQtNDc3Mi05OTk3LTY2ODI4NGU3NzJjYQDwf///6wA="
  }
}

Example response if no documents were found:

{
  "data": {
    "documents": [],
    "nextPageState": null
  }
}

Signature

Use the find command.

curl -sS -L -X POST "API_ENDPOINT/api/json/v1/KEYSPACE_NAME/COLLECTION_NAME" \
--header "Token: APPLICATION_TOKEN" \
--header "Content-Type: application/json" \
--data '{
  "find": {
    "filter": FILTER,
    "sort": SORT,
    "projection": PROJECTION,
    "options": {
      "includeSimilarity": BOOLEAN,
      "skip": INTEGER,
      "limit": INTEGER
    }
  }
}'

Parameters

Name Type Summary

Name	Type	Summary
`filter`	`object`	Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match the filter criteria. Filters can improve performance by reducing the number of documents that the Data API processes. You must use `&` to escape any `.` or `&` in field names in the filter clause. You cannot use `&` to escape any other characters. For more information, see Work with `.` and `&` in field names (HTTP). For a list of available filter operators and more examples, see Filter operators for collections (HTTP). Filters can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in a filter. For an example, see Use filters to find documents.
`sort`	`object`	Optional. Sorts documents by one or more fields, or performs a vector search. You must use `&` to escape any `.` or `&` in field names in the sort clause. You cannot use `&` to escape any other characters. For more information, see Work with `.` and `&` in field names (HTTP). For more information, see Sort clauses for collections (HTTP). Sort clauses can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in sort queries. For vector searches, this parameter can use `$vector`. For examples, see Use sorting to find documents and Use vector search to find documents.
`projection`	`object`	Optional. Controls which fields are included or excluded in the returned document. You must use `&` to escape any `.` or `&` in field names in the projection clause. You cannot use `&` to escape any other characters. For more information, see Work with `.` and `&` in field names (HTTP). For more information, see Projections for collections (HTTP). Default: The default projection for the collection. All fields prefixed with `$` are excluded by default and will only be returned if you include them in the projection. `_id` is included by default and will always be returned unless you exclude it from the projection. For examples, see Include only specific fields in the response and Exclude specific fields from the response.
`options`	`object`	Optional. The options for this operation. See Properties of `options` for more details.

filter

object

Optional. An object that defines filter criteria using the Data API filter syntax. The method only finds documents that match the filter criteria. Filters can improve performance by reducing the number of documents that the Data API processes.

You must use & to escape any . or & in field names in the filter clause. You cannot use & to escape any other characters. For more information, see Work with . and & in field names (HTTP).

For a list of available filter operators and more examples, see Filter operators for collections (HTTP).

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in a filter.

For an example, see Use filters to find documents.

sort

object

Optional. Sorts documents by one or more fields, or performs a vector search.

You must use & to escape any . or & in field names in the sort clause. You cannot use & to escape any other characters. For more information, see Work with . and & in field names (HTTP).

For more information, see Sort clauses for collections (HTTP).

Sort clauses can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in sort queries.

For vector searches, this parameter can use $vector.

For examples, see Use sorting to find documents and Use vector search to find documents.

projection

object

Optional. Controls which fields are included or excluded in the returned document.

You must use & to escape any . or & in field names in the projection clause. You cannot use & to escape any other characters. For more information, see Work with . and & in field names (HTTP).

For more information, see Projections for collections (HTTP).

Default: The default projection for the collection. All fields prefixed with $ are excluded by default and will only be returned if you include them in the projection. _id is included by default and will always be returned unless you exclude it from the projection.

For examples, see Include only specific fields in the response and Exclude specific fields from the response.

options

object

Optional. The options for this operation. See Properties of options for more details.

Properties of `options`
Name	Type	Summary
`includeSimilarity`	`boolean`	Optional. Whether to include a `$similarity` property in the response. The `$similarity` value represents the closeness of the sort vector and the document’s vector. This parameter only applies if you use a vector search. For an example, see Include the similarity score with the result. Default: False
`skip`	`integer`	Optional. The number of documents to bypass (skip) before returning documents. The API excludes the first `n` documents matching the query, and the results begin at the `n+1` document. This parameter only applies if you also explicitly specify an ascending or descending sort criterion. This parameter is not valid with vector search. For an example, see Skip documents.
`limit`	`integer`	Optional. The maximum number of documents to fetch. For vector search, a lower limit reduces the accuracy of the search and the time required for the search. For an example, see Limit the number of documents returned.
`pageState`	`string`	Optional. The value of `status.nextPageState` from the previous request. Used to request the next page of results.

Examples

The following examples demonstrate how to find documents in a collection.

Use filters to find documents

You can use a filter to find documents that match specific criteria. For example, you can find documents with an is_checked_out value of false and a number_of_pages value less than 300.

For a list of available filter operators and more examples, see Filter operators for collections (HTTP).

Filters can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in a filter.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {"$and": [
      {"is_checked_out": false},
      {"number_of_pages": {"$lt": 300}}
    ]}
  }
}'

Use vector search to find documents

To find the documents whose $vector value is most similar to a given vector, use a sort with the vector embeddings that you want to match. For more information, see Find data with vector search.

Vector search is only available for vector-enabled collections. For more information, see Create a collection that can store vector embeddings and $vector in collections (HTTP).

You can provide the search vector as an array of floats, or you can use $binary to provide the search vector as a Base64-encoded string. $binary can be more performant.

For more information about how to convert an array of floats to a Base64-encoded string, see Binary encoding of vector embeddings.

Array of floats

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "sort": { "$vector": [0.08, -0.62, 0.39] }
  }
}'

$binary

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "sort": { "$vector": {"$binary": "PaPXCr8euFI+x64U"} }
  }
}'

Use sorting to find documents

You can use a sort clause to sort documents by one or more fields.

For more information, see Sort clauses for collections (HTTP).

Sort clauses can use only indexed fields. If you apply selective indexing when you create a collection, you cannot reference non-indexed fields in sort queries.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": { "metadata.language": "English" },
    "sort": {
      "rating": 1,
      "title": -1
    }
  }
}'

Use an empty filter to find all documents

To find all documents, use an empty filter.

You should avoid this if you have a large number of documents.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {}
  }
}'

Include the similarity score with the result

If you use a vector search to find documents, you can also include a $similarity property for each document in the result. The $similarity value represents the closeness of the sort vector and the document’s vector.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "sort": { "$vector": [0.08, -0.62, 0.39] },
    "options": { "includeSimilarity": true }
  }
}'

Include only specific fields in the response

To specify which fields to include or exclude in the returned documents, use a projection.

All fields prefixed with $ are excluded by default and will only be returned if you include them in the projection. _id is included by default and will always be returned unless you exclude it from the projection.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {"metadata.language": "English"},
    "projection": {"is_checked_out": true, "title": true}
  }
}'

Exclude specific fields from the response

To specify which fields to include or exclude in the returned document, use a projection.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {"metadata.language": "English"},
    "projection": {"is_checked_out": false, "title": false}
  }
}'

Limit the number of documents returned

Specify a limit to only fetch up to a certain number of documents.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {"metadata.language": "English"},
    "options": {
      "limit": 10
    }
  }
}'

Skip documents

You can specify a number of documents to skip (bypass) before returning documents.

You can only do this if your find explicitly includes an ascending or descending sort criterion. You cannot do this in conjunction with vector search.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": { "metadata.language": "English" },
    "sort": {
      "rating": 1,
      "title": -1
    },
    "options": {
      "skip": 5
    }
  }
}'

Use filter, sort, and projection together

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {"$and": [
      {"is_checked_out": false},
      {"number_of_pages": {"$lt": 300}}
    ]},
    "sort": {
      "rating": 1,
      "title": -1
    },
    "projection": {"is_checked_out": true, "title": true}
  }
}'

Iterate over found documents

If the response includes a non-null nextPageState, then the specified sort or filter operation supports pagination, and more documents than the ones already returned exist.

To fetch additional documents, you must send a request with the nextPageState value from your previous request. For example:

Send an initial request

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {"is_checked_out": false}
  }
}'

Get the data.documents.nextPageState value from the response

{
  "data": {
    "documents": [
      {
        "_id": { "$uuid": "018e65c9-df45-7913-89f8-175f28bd7f74" }
      },
      {
        "_id": { "$uuid": "018e65c9-e33d-749b-9386-e848739582f0" }
      }
    ],
    "nextPageState": "NEXT_PAGE_STATE"
  }
}

Use the data.documents.nextPageState from the previous response to request the next page of results.

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {"is_checked_out": false},
    "options": {
      "pageState": "NEXT_PAGE_STATE_FROM_PRIOR_RESPONSE"
    }
  }
}'

Once nextPageState is null, you have fetched all matching documents.

{
  "data": {
    "documents": [
      {
        "_id": { "$uuid": "018e65c9-df45-7913-89f8-175f28bd7f74" }
      },
      {
        "_id": { "$uuid": "018e65c9-e33d-749b-9386-e848739582f0" }
      }
    ],
    "nextPageState": null
  }
}

Work with `.` and `&` in field names

You must use & to escape any . or & in field names when the field is used in a filter, sort, projection, update, or indexing clause. Dot notation, which is used to reference nested fields, should not be escaped. For more information, see Work with . and & in field names (HTTP).

For example, in the following document, you would use escaping like this: areas.r&&d, costs.price&.usd, and costs.price&.cad.

{
  "areas": {
    "r&d": true,
    "design": false
  },
  "costs": {
    "price.usd": 100,
    "price.cad": 90
  }
}

curl -sS -L -X POST "API_ENDPOINT/v1/KEYSPACE_NAME/COLLECTION_NAME" \
  --header "Token: APPLICATION_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
  "find": {
    "filter": {"$and": [
      {"areas.r&&d": false},
      {"costs.price&.usd": {"$lt": 300}}
    ]},
    "sort": {
      "costs.price&.usd": 1
    },
    "projection": {"areas.r&&d": true, "costs.price&.cad": true}
  }
}'

Find documents (HTTP)

Result

Signature

Parameters

Examples

Use filters to find documents

Use vector search to find documents

Use sorting to find documents

Use an empty filter to find all documents

Include the similarity score with the result

Include only specific fields in the response

Exclude specific fields from the response

Limit the number of documents returned

Skip documents

Use filter, sort, and projection together

Iterate over found documents

Work with `.` and `&` in field names

Was this helpful?

Give Feedback