`Get`

Get( ref, [ts] )

Get( ref, [ts] )

Get( ref, [ts] )

Get( ref, [ts] )

get( ref, [ts] )

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

ref

Reference or a Set Reference

A document reference that uniquely identifies a document, or a set reference from a Match call.

ts

Long or Timestamp

Optional - Return the document at the specified point in time (number of UNIX microseconds or Timestamp). The default is the current time.

For large values of ts (positive or negative), you may need to express the value in a String to maintain numeric precision (Fauna uses 64-bit signed integers, whereas JavaScript uses 53-bit signed integers).

Returns

A document containing both the document data and metadata:

Field Name Field Type Definition and Requirements

Field Name	Field Type	Definition and Requirements
`ref`	Reference	The reference identifies the document retrieved.
`data`	Object	Optional - the document data retrieved at the location pointed to by `ref`. This field is returned only if the document contains a `data` field.
`ts`	Long	The timestamp associated with the creation of the requested document version, according to the `ts` parameter. Effectively, this timestamp represents the most recent modification of the document as of the `ts` parameter.

ref

Reference

The reference identifies the document retrieved.

data

Object

Optional - the document data retrieved at the location pointed to by ref.

This field is returned only if the document contains a data field.

ts

Long

The timestamp associated with the creation of the requested document version, according to the ts parameter. Effectively, this timestamp represents the most recent modification of the document as of the ts parameter.

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:

try
{
    Value result = await client.Query(
        Get(Ref(Collection("spells"), "181388642046968320"))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(ref: RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1603756365810000),data: ObjectV(name: StringV(Fire Beak),element: Arr(StringV(air), StringV(fire)),spellbook: RefV(id = "181388642139243008", collection = RefV(id = "spellbooks", collection = RefV(id = "collections")))))

result, err := client.Query(
	f.Get(f.Ref(f.Collection("spells"), "181388642046968320")))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:map[element:[air fire] name:Fire Beak spellbook:{181388642139243008 0xc000170360 0xc000170360 <nil>}] ref:{181388642046968320 0xc000170180 0xc000170180 <nil>} ts:1603747176520000]

System.out.println(
    client.query(
        Get(Ref(Collection("spells"), Value("181388642046968320")))
    ).get());

{ref: ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1593465108040000, data: {name: "Fire Beak", element: ["air", "fire"], spellbook: ref(id = "181388642139243008", collection = ref(id = "spellbooks", collection = ref(id = "collections")))}}

client.query(
  q.Get(q.Ref(q.Collection('spells'), '181388642046968320'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  ref: Ref(Collection("spells"), "181388642046968320"),
  ts: 1592113594660000,
  data: {
    name: 'Fire Beak',
    element: [ 'air', 'fire' ],
    spellbook: Ref(Collection("spellbooks"), "181388642139243008")
  }
}

result = client.query(
  q.get(q.ref(q.collection("spells"), "181388642046968320"))
)
print(result)

{'ref': Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592959119480000, 'data': {'name': 'Fire Beak', 'element': ['air', 'fire'], 'spellbook': Ref(id=181388642139243008, collection=Ref(id=spellbooks, collection=Ref(id=collections)))}}

Get(Ref(Collection('spells'), '181388642046968320'))

{
  ref: Ref(Collection("spells"), "181388642046968320"),
  ts: 1624310416790000,
  data: {
    name: 'Fire Beak',
    element: [ 'air', 'fire' ],
    spellbook: Ref(Collection("spellbooks"), "181388642139243008")
  }
}

Query metrics:

bytesIn: 65
bytesOut: 347
computeOps: 1
readOps: 1
writeOps: 0
readBytes: 214
writeBytes: 0
queryTime: 3ms
retries: 0

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.

try
{
    Value result = await client.Query(
        Arr(
            Get(Ref(Collection("spells"), "181388642046968320")),
            Get(Ref(Collection("spells"), "181388642071085568")),
            Get(Ref(Collection("spells"), "181388642088911360"))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

Arr(ObjectV(ref: RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1603756365810000),data: ObjectV(name: StringV(Fire Beak),element: Arr(StringV(air), StringV(fire)),spellbook: RefV(id = "181388642139243008", collection = RefV(id = "spellbooks", collection = RefV(id = "collections"))))), ObjectV(ref: RefV(id = "181388642071085568", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1603756365810000),data: ObjectV(name: StringV(Water Dragon's Claw),element: Arr(StringV(water), StringV(fire)),spellbook: RefV(id = "181388642139243008", collection = RefV(id = "spellbooks", collection = RefV(id = "collections"))))), ObjectV(ref: RefV(id = "181388642088911360", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1603756293930000),data: ObjectV(name: StringV(Hippo's Wallow),element: Arr(StringV(water), StringV(earth)))))

result, err := client.Query(
	f.Arr{
		f.Get(f.Ref(f.Collection("spells"), "181388642046968320")),
		f.Get(f.Ref(f.Collection("spells"), "181388642071085568")),
		f.Get(f.Ref(f.Collection("spells"), "181388642088911360")),
	})

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

[map[data:map[element:[air fire] name:Fire Beak spellbook:{181388642139243008 0xc000146420 0xc000146420 <nil>}] ref:{181388642046968320 0xc000146240 0xc000146240 <nil>} ts:1603747176520000] map[data:map[element:[water fire] name:Water Dragon's Claw spellbook:{181388642139243008 0xc0001468a0 0xc0001468a0 <nil>}] ref:{181388642071085568 0xc000146600 0xc000146600 <nil>} ts:1603747176520000] map[data:map[element:[water earth] name:Hippo's Wallow] ref:{181388642088911360 0xc000146a80 0xc000146a80 <nil>} ts:1603747162980000]]

System.out.println(
    client.query(
        Arr(
            Get(Ref(Collection("spells"),Value("181388642046968320"))),
            Get(Ref(Collection("spells"),Value("181388642071085568"))),
            Get(Ref(Collection("spells"),Value("181388642088911360")))
        )
    ).get());

[{ref: ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1593465108040000, data: {name: "Fire Beak", element: ["air", "fire"], spellbook: ref(id = "181388642139243008", collection = ref(id = "spellbooks", collection = ref(id = "collections")))}}, {ref: ref(id = "181388642071085568", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1593465108040000, data: {name: "Water Dragon's Claw", element: ["water", "fire"], spellbook: ref(id = "181388642139243008", collection = ref(id = "spellbooks", collection = ref(id = "collections")))}}, {ref: ref(id = "181388642088911360", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1593464839880000, data: {name: "Hippo's Wallow", element: ["water", "earth"]}}]

client.query([
  q.Get(q.Ref(q.Collection('spells'), '181388642046968320')),
  q.Get(q.Ref(q.Collection('spells'), '181388642071085568')),
  q.Get(q.Ref(q.Collection('spells'), '181388642088911360')),
])
.then((ret) => console.log(util.inspect(ret, { depth: null })))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

[
  {
    ref: Ref(Collection("spells"), "181388642046968320"),
    ts: 1592270304740000,
    data: {
      name: 'Fire Beak',
      element: [ 'air', 'fire' ],
      spellbook: Ref(Collection("spellbooks"), "181388642139243008")
    }
  },
  {
    ref: Ref(Collection("spells"), "181388642071085568"),
    ts: 1592270304740000,
    data: {
      name: "Water Dragon's Claw",
      element: [ 'water', 'fire' ],
      spellbook: Ref(Collection("spellbooks"), "181388642139243008")
    }
  },
  {
    ref: Ref(Collection("spells"), "181388642088911360"),
    ts: 1592270304740000,
    data: { name: "Hippo's Wallow", element: [ 'water', 'earth' ] }
  }
]

result = client.query(
  [
    q.get(q.ref(q.collection("spells"), "181388642046968320")),
    q.get(q.ref(q.collection("spells"), "181388642071085568")),
    q.get(q.ref(q.collection("spells"), "181388642088911360"))
  ]
)
print(result)

[{'ref': Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592959519240000, 'data': {'name': 'Fire Beak', 'element': ['air', 'fire'], 'spellbook': Ref(id=181388642139243008, collection=Ref(id=spellbooks, collection=Ref(id=collections)))}}, {'ref': Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592959519240000, 'data': {'name': "Water Dragon's Claw", 'element': ['water', 'fire'], 'spellbook': Ref(id=181388642139243008, collection=Ref(id=spellbooks, collection=Ref(id=collections)))}}, {'ref': Ref(id=181388642088911360, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1592959517110000, 'data': {'name': "Hippo's Wallow", 'element': ['water', 'earth']}}]

[
  Get(Ref(Collection('spells'), '181388642046968320')),
  Get(Ref(Collection('spells'), '181388642071085568')),
  Get(Ref(Collection('spells'), '181388642088911360'))
]

[
  {
    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' ] }
  }
]

Query metrics:

bytesIn: 199
bytesOut: 905
computeOps: 1
readOps: 3
writeOps: 0
readBytes: 550
writeBytes: 0
queryTime: 7ms
retries: 0

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).

try
{
    Value result = await client.Query(
        Arr(
            If(
                Exists(Ref(Collection("spells"), "181388642046968320")),
                Get(Ref(Collection("spells"), "181388642046968320")),
                false
            ),
            If(
                Exists(Ref(Collection("spells"), "123")),
                Get(Ref(Collection("spells"), "123")),
                false
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

Arr(ObjectV(ref: RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections"))),ts: LongV(1653349514650000),data: ObjectV(name: StringV(Fire Beak),element: Arr(StringV(air), StringV(fire)),spellbook: RefV(id = "181388642139243008", collection = RefV(id = "spellbooks", collection = RefV(id = "collections"))))), BooleanV(False))

result, err := client.Query(
	f.Arr{
		f.If(
			f.Exists(f.Ref(f.Collection("spells"), "181388642046968320")),
			f.Get(f.Ref(f.Collection("spells"), "181388642046968320")),
			false,
		),
		f.If(
			f.Exists(f.Ref(f.Collection("spells"), "123")),
			f.Get(f.Ref(f.Collection("spells"), "123")),
			false,
		),
	})

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

[map[data:map[element:[air fire] name:Fire Beak spellbook:{181388642139243008 0x140001944e0 0x140001944e0 <nil>}] ref:{181388642046968320 0x14000194300 0x14000194300 <nil>} ts:1653349417380000] false]

System.out.println(
    client.query(
        Arr(
            If(
                Exists(Ref(Collection("spells"),Value("181388642046968320"))),
                Get(Ref(Collection("spells"),Value("181388642046968320"))),
                Value(false)
            ),
            If(
                Exists(Ref(Collection("spells"),Value("123"))),
                Get(Ref(Collection("spells"),Value("123"))),
                Value(false)
            )
        )
    ).get());

[{ref: ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections"))), ts: 1653349305410000, data: {name: "Fire Beak", element: ["air", "fire"], spellbook: ref(id = "181388642139243008", collection = ref(id = "spellbooks", collection = ref(id = "collections")))}}, false]

client.query([
  q.If(
    q.Exists(q.Ref(q.Collection('spells'), '181388642046968320')),
    q.Get(q.Ref(q.Collection('spells'), '181388642046968320')),
    false
  ),
  q.If(
    q.Exists(q.Ref(q.Collection('spells'), '123')),
    q.Get(q.Ref(q.Collection('spells'), '123')),
    false
  ),
])
.then((ret) => console.log(util.inspect(ret, { depth: null })))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

[
  {
    ref: Ref(Collection("spells"), "181388642046968320"),
    ts: 1653349010350000,
    data: {
      name: 'Fire Beak',
      element: [ 'air', 'fire' ],
      spellbook: Ref(Collection("spellbooks"), "181388642139243008")
    }
  },
  false
]

result = client.query(
  [
    q.if_(
      q.exists(q.ref(q.collection("spells"), "181388642046968320")),
      q.get(q.ref(q.collection("spells"), "181388642046968320")),
      False
    ),
    q.if_(
      q.exists(q.ref(q.collection("spells"), "123")),
      q.get(q.ref(q.collection("spells"), "123")),
      False
    ),
  ]
)
print(result)

[{'ref': Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))), 'ts': 1653349098690000, 'data': {'name': 'Fire Beak', 'element': ['air', 'fire'], 'spellbook': Ref(id=181388642139243008, collection=Ref(id=spellbooks, collection=Ref(id=collections)))}}, False]

[
  // This document exists
  If(
    Exists(Ref(Collection('spells'), '181388642046968320')),
    Get(Ref(Collection('spells'), '181388642046968320')),
    false
  ),
  // This document does not exist
  If(
    Exists(Ref(Collection('spells'), '123')),
    Get(Ref(Collection('spells'), '123')),
    false
  ),
]

[
  {
    ref: Ref(Collection("spells"), "181388642046968320"),
    ts: 1653348867010000,
    data: {
      name: 'Fire Beak',
      element: [ 'air', 'fire' ],
      spellbook: Ref(Collection("spellbooks"), "181388642139243008")
    }
  },
  false
]

Query metrics:

bytesIn: 295
bytesOut: 355
computeOps: 1
readOps: 2
writeOps: 0
readBytes: 127
writeBytes: 0
queryTime: 5ms
retries: 0

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!

Get

Description

Errors

Parameter

Returns

Examples

Retrieve a document by reference

Fetch multiple documents by reference

Handle "document not found"

Keyboard shortcuts

While reading

While searching

URL fragments

`Get`