Skip to Navigation
Get Documents Command
-
Use
GetDocumentsCommandto retrieve documents from the database. -
In this page:
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: ...| Parameter | 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: ...| Parameter | 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: ...| Parameter | 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_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: ...| Parameter | 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.resultsExample 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.resultsExample 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
Related Articles