See on GitHub

    Commands: Get Documents

    Get single document

    GetDocumentsCommand can be used to retrieve a single document

    Syntax:

    public static function forSingleDocument(string $id, StringArray|array|null $includes = null, bool $metadataOnly = false): GetDocumentsCommand;
    Parameters Type Description
    id string ID of the documents to get
    includes StringArray or array or null Related documents to fetch along with the document
    metadataOnly bool Whether to fetch the whole document or just its metadata.

    Example:

    $command = GetDocumentsCommand::forSingleDocument("orders/1-A", null, false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $documentsResult */
$documentsResult = $command->getResult();
$order = $documentsResult->getResults()[0];

    Get multiple documents

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

    Syntax:

    public static function forMultipleDocuments(StringArray|array|null $ids, StringArray|array|null $includes, bool $metadataOnly = false): GetDocumentsCommand;
    Parameters Type Description
    ids StringArray or array or null IDs of the documents to get
    includes StringArray or array or null Related documents to fetch along with the documents
    metadataOnly bool Whether to fetch whole documents or just the metadata

    Example I

    $command = GetDocumentsCommand::forMultipleDocuments(["orders/1-A", "employees/3-A"], null, false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$order = $result->getResults()[0];
$employee = $result->getResults()[1];

    Example II - Using Includes

    // Fetch employees/5-A and his boss.
$command = GetDocumentsCommand::forSingleDocument("employees/5-A", [ "ReportsTo" ], false);
$session->advanced()->getRequestExecutor()->execute($command);
/** @var GetDocumentsResult $result */
$result = $command->getResult();
$employee = $result->getResults()[0];
if (array_key_exists("ReportsTo", $employee)) {
    $bossId = $employee["ReportsTo"];

    $boss = $result->getIncludes()[$bossId];
}

    Example III - Missing Documents

    // Assuming that products/9999-A doesn't exist.
$command = GetDocumentsCommand::forMultipleDocuments([ "products/1-A", "products/9999-A", "products/3-A" ], null, false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$products = $result->getResults(); // products/1-A, null, products/3-A

    Get paged documents

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

    Syntax:

    public static function withStartAndPageSize(int $start, int $pageSize): GetDocumentsCommand;
    Parameters Type Description
    start int number of documents that should be skipped
    pageSize int maximum number of documents that will be retrieved

    Example:

    $command = GetDocumentsCommand::withStartAndPageSize(0, 128);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$firstDocs = $result->getResults();

    Get documents by ID prefix

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

    Syntax:

    public static function withStartWith(
    ?string $startWith,
    ?string $startAfter,
    ?string $matches,
    ?string $exclude,
    int $start,
    int $pageSize,
    bool $metadataOnly
): GetDocumentsCommand;
    Parameters Type Description
    startWith ?string prefix for which documents should be returned
    startAfter ?string skip 'document fetching' until the given ID is found, and return documents after that ID (default: None)
    matches ?string pipe ('|') separated values for which document IDs (after startWith) should be matched ('?' any single character, '*' any characters)
    exclude ?string pipe ('|') separated values for which document IDs (after startWith) should not be matched ('?' any single character, '*' any characters)
    start int number of documents that should be skipped
    pageSize int maximum number of documents that will be retrieved
    metadataOnly 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::withStartWith(
    startWith: "products",
    startAfter: null,
    matches: null,
    exclude: null,
    start: 0,
    pageSize: 128,
    metadataOnly: false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$products = $result->getResults();

    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
$command = GetDocumentsCommand::withStartWith(
    startWith: "products",
    startAfter: null,
    matches: "1*|2*",
    exclude: null,
    start: 0,
    pageSize: 128,
    metadataOnly: false);
$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$products = $result->getResults();

    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
$command = GetDocumentsCommand::withStartWith(
    startWith: "products",
    startAfter: null,
    matches: "1?1",
    exclude: null,
    start: 0,
    pageSize: 128,
    metadataOnly: false);

$session->advanced()->getRequestExecutor()->execute($command);

/** @var GetDocumentsResult $result */
$result = $command->getResult();
$products = $result->getResults();

    related articlesRelated Articles

    Commands

    Home / Docs / Client Api / Commands / Documents / Get