Commands: Get Documents


Get single document

GetDocumentsCommand can be used to retrieve a single document

Syntax:

# GetDocumentsCommand.from_single_id(...)
@classmethod
def from_single_id(
    cls, key: str, includes: List[str] = None, metadata_only: bool = None
) -> GetDocumentsCommand: ...
Parameters Type Description
key str ID of the documents to get
includes List[str] Related documents to fetch along with the document
metadata_only bool Whether to fetch the whole document or just the metadata.

Example:

command = GetDocumentsCommand.from_single_id("orders/1-A", None, False)
session.advanced.request_executor.execute_command(command)
order = command.result.results[0]

Get multiple documents

GetDocumentsCommand can also be used to retrieve a list of documents.

Syntax:

# GetDocumentsCommand.from_multiple_ids(...)
@classmethod
def from_multiple_ids(
    cls,
    keys: List[str],
    includes: List[str] = None,
    counter_includes: List[str] = None,
    time_series_includes: List[str] = None,
    compare_exchange_value_includes: List[str] = None,
    metadata_only: bool = False,
) -> GetDocumentsCommand: ...
Parameters Type Description
keys List[str] IDs of the documents to get
includes List[str] Related documents to fetch along with the documents
metadata_only bool Whether to fetch whole documents or just the metadata

Example I

command = GetDocumentsCommand.from_multiple_ids(["orders/1-A", "employees/3-A"])
session.advanced.request_executor.execute_command(command)
order = command.result.results[0]
employee = command.result.results[1]

Example II - Using Includes

# Fetch employees/5-A and his boss.
command = GetDocumentsCommand.from_single_id("employees/5-A", ["ReportsTo"], False)
session.advanced.request_executor.execute_command(command)
employee = command.result.results[0]
boss = command.result.includes.get(employee.get("ReportsTo", None), None)

Example III - Missing Documents

# Assuming that products/9999-A doesn't exist
command = GetDocumentsCommand.from_multiple_ids(["products/1-A", "products/9999-A", "products/3-A"])
session.advanced.request_executor.execute_command(command)
products = command.result.results  # products/1-A, products/3-A

Get paged documents

GetDocumentsCommand can also be used to retrieve a paged set of documents.

Syntax:

# GetDocumentsCommand.from_paging(...)
@classmethod
def from_paging(cls, start: int, page_size: int) -> GetDocumentsCommand: ...
Parameters Type Description
start int number of documents that should be skipped
page_size int maximum number of documents that will be retrieved

Example:

command = GetDocumentsCommand.from_paging(0, 128)
session.advanced.request_executor.execute_command(command)
first_10_docs = command.result.results

Get documents by ID prefix

GetDocumentsCommand can be used to retrieve multiple documents for a specified ID prefix.

Syntax:

# GetDocumentsCommand.from_starts_with(...)
@classmethod
def from_starts_with(
    cls,
    start_with: str,
    start_after: str = None,
    matches: str = None,
    exclude: str = None,
    start: int = None,
    page_size: int = None,
    metadata_only: bool = None,
) -> GetDocumentsCommand: ...
Parameters Type Description
start_with str prefix for which documents should be returned
start_after str skip 'document fetching' until the given ID is found, and return documents after that ID (default: None)
matches str pipe ('|') separated values for which document IDs (after start_with) should be matched ('?' any single character, '*' any characters)
exclude str pipe ('|') separated values for which document IDs (after start_with) should not be matched ('?' any single character, '*' any characters)
start int number of documents that should be skipped
page_size int maximum number of documents that will be retrieved
metadata_only bool specifies whether or not only document metadata should be returned

Example I

# return up to 128 documents with key that starts with 'products'
command = GetDocumentsCommand.from_starts_with("products", start=0, page_size=128)
session.advanced.request_executor.execute_command(command)
products = command.result.results

Example II

# return up to 128 documents with key that starts with 'products/'
# and rest of the key begins with "1" or "2" e.g. products/10, products/25
commands = GetDocumentsCommand.from_starts_with("products", matches="1*2|2*", start=0, page_size=128)
session.advanced.request_executor.execute_command(command)
products = command.result.results

Example III

# return up to 128 documents with key that starts with 'products/'
# and rest of the key have length of 3, begins and ends with "1"
# and contains any character at 2nd position e.g. products/101, products/1B1
commands = GetDocumentsCommand.from_starts_with("products", matches="1?1", start=0, page_size=128)
session.advanced.request_executor.execute_command(command)
products = command.result.results