Get
Get( ref, [ts] )
Description
The Get
function retrieves a single document identified by
a Reference. An optional timestamp (ts
- a Long) can be
provided to retrieve the document version that existed at the specific
date and time. If the timestamp is omitted, the default is the current
time.
When a Set Reference (from a Match
expression) is passed
to Get
, the first document (based on the sort order of the
index) in the set is returned. If the set contains no entries,
Get
fails with a "set not found" error.
Errors
-
If the document does not exist, a "document not found" error is returned.
To avoid such errors, use the
Exists
function in a conditional expression in your query. See the example, below. -
If the client does not have read permission for the document, a "permission denied" error is returned.
-
If a Set Reference is provided and the set does not exist, or contains no entries, a "set not found" error is returned.
Parameter
Parameter | Type | Definition and Requirements | ||
---|---|---|---|---|
|
A document reference that uniquely identifies a document, or a set
reference from a |
|||
|
Optional - Return the document at the specified point in time (number of UNIX microseconds or Timestamp). The default is the current time.
|
Returns
A document containing both the document data and metadata:
Field Name | Field Type | Definition and Requirements |
---|---|---|
|
The reference identifies the document retrieved. |
|
|
Optional - the document data retrieved at the location pointed to by This field is returned only if the document contains a |
|
|
The timestamp associated with the creation of the requested document
version, according to the |
Examples
Retrieve a document by reference
The following query retrieves an document by providing a reference to the collection named "spells" with a specific document ID:
{
ref: Ref(Collection("spells"), "181388642046968320"),
ts: 1624310416790000,
data: {
name: 'Fire Beak',
element: [ 'air', 'fire' ],
spellbook: Ref(Collection("spellbooks"), "181388642139243008")
}
}
Fetch multiple documents by reference
To retrieve multiple references in a single operation, use an array to group and return multiple documents. The following example returns three different identifiers from the "spells" collection in a single query. This saves network bandwidth and processing by grouping several requests for data into the same operation.
[
{
ref: Ref(Collection("spells"), "181388642046968320"),
ts: 1624450221980000,
data: {
name: 'Fire Beak',
element: [ 'air', 'fire' ],
spellbook: Ref(Collection("spellbooks"), "181388642139243008")
}
},
{
ref: Ref(Collection("spells"), "181388642071085568"),
ts: 1624450221980000,
data: {
name: "Water Dragon's Claw",
element: [ 'water', 'fire' ],
spellbook: Ref(Collection("spellbooks"), "181388642139243008")
}
},
{
ref: Ref(Collection("spells"), "181388642088911360"),
ts: 1624450219860000,
data: { name: "Hippo's Wallow", element: [ 'water', 'earth' ] }
}
]
Handle "document not found"
The following example demonstrates the use of a conditional expression to handle document existence. Both variations are included by using an array (per the previous example, above).
[
{
ref: Ref(Collection("spells"), "181388642046968320"),
ts: 1653348867010000,
data: {
name: 'Fire Beak',
element: [ 'air', 'fire' ],
spellbook: Ref(Collection("spellbooks"), "181388642139243008")
}
},
false
]
Is this article helpful?
Tell Fauna how the article can be improved:
Visit Fauna's forums
or email docs@fauna.com
Thank you for your feedback!