Search Documents

async AsyncCogniteClient.documents.search(
query: str,
highlight: bool = False,
filter: Filter | dict[str, Any] | None = None,
sort: DocumentSort | SortableSourceFileProperty | SortableDocumentProperty | str | list[str] | tuple[SortableSourceFileProperty | SortableDocumentProperty | str | list[str], Literal['asc', 'desc']] | None = None,
limit: int = 25,
) → DocumentList | DocumentHighlightList

Search documents.

This endpoint lets you search for documents by using advanced filters and free text queries. Free text queries are matched against the documents’ filenames and contents. For more information, see endpoint documentation referenced above.

Parameters:

  • query (str) – The free text search query.

  • highlight (bool) – Whether or not matches in search results should be highlighted.

  • filter (Filter | dict[str, Any] | None) – The filter to narrow down the documents to search.

  • sort (DocumentSort | SortableProperty | tuple[SortableProperty, Literal['asc', 'desc']] | None) – The property to sort by. The default order is ascending.

  • limit (int) – Maximum number of items to return. When using highlights, the maximum value is reduced to 20. Defaults to 25.

Returns:

List of search results. If highlight is True, a DocumentHighlightList is returned, otherwise a DocumentList is returned.

Return type:

DocumentList | DocumentHighlightList

Examples

Search for text “pump 123” in PDF documents in your CDF project:

>>> from cognite.client import CogniteClient
>>> from cognite.client.data_classes import filters
>>> from cognite.client.data_classes.documents import DocumentProperty
>>> client = CogniteClient()
>>> # async_client = AsyncCogniteClient()  # another option
>>> is_pdf = filters.Equals(DocumentProperty.mime_type, "application/pdf")
>>> documents = client.documents.search("pump 123", filter=is_pdf)

Find all documents with exact text ‘CPLEX Error 1217: No Solution exists.’ in plain text files created the last week in your CDF project and highlight the matches:

>>> from datetime import datetime, timedelta
>>> from cognite.client.data_classes import filters
>>> from cognite.client.data_classes.documents import DocumentProperty
>>> from cognite.client.utils import timestamp_to_ms
>>> is_plain_text = filters.Equals(DocumentProperty.mime_type, "text/plain")
>>> last_week = filters.Range(
...     DocumentProperty.created_time,
...     gt=timestamp_to_ms(datetime.now() - timedelta(days=7)),
... )
>>> documents = client.documents.search(
...     '"CPLEX Error 1217: No Solution exists."',
...     highlight=True,
...     filter=filters.And(is_plain_text, last_week),
... )