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 ref. An optional timestamp (ts) can be provided to retrieve the document which existed at the specific date and time. If the timestamp is omitted the default is the current time.

Get is also useful for retrieving the first document from a Match result.

Errors

If the document does not exist, a "document not found" error is returned. Use the exists predicate to avoid "document not found" errors.
If the client does not have read permission for the document, a "permission denied" error is returned.

Parameter

Argument Type Definition and Requirements

ref

Reference

A document reference that uniquely identifies a document.

ts

Integer 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 described below.

Field Name Field Type Definition and Requirements

Field Name	Field Type	Definition and Requirements
`ref`	Reference	The reference identifies the document retrieved.
`data`	Object	The document data retrieved at the location pointed to by ref.
`ts`	Integer	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

The document data retrieved at the location pointed to by ref.

ts

Integer

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

The following query retrieves an document by providing a reference to the collection named "spells" at a specific id:

client.Query(Get(Ref(Collection("spells"), "181388642046968320")));

{
  "ref": { "@ref": "classes/spells/181388642046968320" },
  "class": { "@ref": "classes/spells" },
  "ts": 1509244539547758,
  "data": {
    "name": "Fire Beak",
    "element": [ "air", "fire" ],
    "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
  }
}

curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{ "get": { "@ref": "classes/spells/181388642046968320" } }'

HTTP/1.1 200 OK
{
  "resource": {
    "ref": { "@ref": "classes/spells/181388642046968320" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539547758,
    "data": {
      "name": "Fire Beak",
      "element": [ "air", "fire" ],
      "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
    }
  }
}

result, _ := client.Query(f.Get(f.RefCollection(f.Collection("spells"), "181388642046968320")))

fmt.Println(result)

map[ref:{181388642046968320 0xc4201c7440 <nil>} ts:1509244539547758 data:map[element:[air fire] name:Fire Beak spellbook:{181388642139243008 0xc4201c77c0 <nil>}]]

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

{
  ref: ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections"))), 
  ts: 1536604020492774, 
  data: {
    name: "Fire Beak", 
    element: ["air", "fire"], 
    spellbooks: 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))

{ ref: Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))),
  ts: 1526677786695156,
  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")))

{
  "ref": { "@ref": "classes/spells/181388642046968320" },
  "class": { "@ref": "classes/spells" },
  "ts": 1509244539547758,
  "data": {
    "name": "Fire Beak",
    "element": [ "air", "fire" ],
    "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
  }
}

client.query(Get(Ref(Collection("spells"), "181388642046968320")))

{
  "ref": { "@ref": "classes/spells/181388642046968320" },
  "class": { "@ref": "classes/spells" },
  "ts": 1509244539547758,
  "data": {
    "name": "Fire Beak",
    "element": [ "air", "fire" ],
    "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
  }
}

To retrieve multiple references in a single operation, utilize the array operator to group and return multiple documents. The following example returns three different identifiers from the spells collection in a single database operation. This saves network bandwidth and processing by grouping several requests for data into the same operation.

client.Query(
  Arr(
    Get(Ref(Collection("spells"), "181388642046968320")),
    Get(Ref(Collection("spells"), "181388642071085568")),
    Get(Ref(Collection("spells"), "181388642088911360"))
  ));

[
  {
    "ref": { "@ref": "classes/spells/181388642046968320" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539547758,
    "data": {
      "name": "Fire Beak",
      "element": [ "air", "fire" ],
      "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
    }
  },
  {
    "ref": { "@ref": "classes/spells/181388642071085568" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539547758,
    "data": {
      "name": "Water Dragon's Claw",
      "element": [ "water", "fire" ],
      "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
    }
  },
  {
    "ref": { "@ref": "classes/spells/181388642088911360" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539235128,
    "data": {
      "name": "Hippo's Wallow",
      "element": [ "water", "earth" ]
    }
  }
]

curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '[
          { "get": { "@ref": "classes/spells/181388642046968320" } },
          { "get": { "@ref": "classes/spells/181388642071085568" } },
          { "get": { "@ref": "classes/spells/181388642088911360" } }
        ]'

HTTP/1.1 200 OK
{
  "resource": [
    {
      "ref": { "@ref": "classes/spells/181388642046968320" },
      "class": { "@ref": "classes/spells" },
      "ts": 1509244539547758,
      "data": {
        "name": "Fire Beak",
        "element": [ "air", "fire" ],
        "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
      }
    },
    {
      "ref": { "@ref": "classes/spells/181388642071085568" },
      "class": { "@ref": "classes/spells" },
      "ts": 1509244539547758,
      "data": {
        "name": "Water Dragon's Claw",
        "element": [ "water", "fire" ],
        "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
      }
    },
    {
      "ref": { "@ref": "classes/spells/181388642088911360" },
      "class": { "@ref": "classes/spells" },
      "ts": 1509244539235128,
      "data": {
        "name": "Hippo's Wallow",
        "element": [ "water", "earth" ]
      }
    }
  ]
}

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

fmt.Println(result)

[
  map[ref:{181388642046968320 0xc4201d6f20 <nil>} ts:1509244539547758 data:map[element:[air fire] name:Fire Beak spellbook:{181388642139243008 0xc4201d72a0 <nil>}]]
  map[ref:{181388642071085568 0xc4201d74e0 <nil>} ts:1509244539547758 data:map[element:[water fire] name:Water Dragon's Claw spellbook:{181388642139243008 0xc4201d7860 <nil>}]]
  map[ref:{181388642088911360 0xc4201d7ac0 <nil>} ts:1509244539235128 data:map[element:[water earth] name:Hippo's Wallow]]
]

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: 1536604020492774, 
     data: {
       name: "Fire Beak", 
       element: ["air", "fire"], 
       spellbooks: ref(id = "181388642139243008", collection = ref(id = "spellbooks", collection = ref(id = "collections")))
     }
   },
   {
     ref: ref(id = "181388642071085568", collection = ref(id = "spells", collection = ref(id = "collections"))), 
     ts: 1536604020513444, 
     data: {
       name: "Water Dragon's Claw", 
       element: ["water", "fire"], 
       spellbooks: ref(id = "181388642139243008", collection = ref(id = "spellbooks", collection = ref(id = "collections")))
     }
   },
   {
     ref: ref(id = "181388642088911360", collection = ref(id = "spells", collection = ref(id = "collections"))), 
     ts: 1536604020270318, 
     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(ret))

[ { ref: Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))),
    ts: 1509244539547758,
    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: 1509244539547758,
    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: 1509244539235128,
    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"))
  ])

[
  {
    "ref": { "@ref": "classes/spells/181388642046968320" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539547758,
    "data": {
      "name": "Fire Beak",
      "element": [ "air", "fire" ],
      "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
    }
  },
  {
    "ref": { "@ref": "classes/spells/181388642071085568" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539547758,
    "data": {
      "name": "Water Dragon's Claw",
      "element": [ "water", "fire" ],
      "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
    }
  },
  {
    "ref": { "@ref": "classes/spells/181388642088911360" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539235128,
    "data": {
      "name": "Hippo's Wallow",
      "element": [ "water", "earth" ]
    }
  }
]

client.query(
  Arr(
    Get(Ref(Collection("spells"), "181388642046968320")),
    Get(Ref(Collection("spells"), "181388642071085568")),
    Get(Ref(Collection("spells"), "181388642088911360"))
  ))

[
  {
    "ref": { "@ref": "classes/spells/181388642046968320" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539547758,
    "data": {
      "name": "Fire Beak",
      "element": [ "air", "fire" ],
      "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
    }
  },
  {
    "ref": { "@ref": "classes/spells/181388642071085568" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539547758,
    "data": {
      "name": "Water Dragon's Claw",
      "element": [ "water", "fire" ],
      "spellbook": { "@ref": "classes/spellbooks/181388642139243008" }
    }
  },
  {
    "ref": { "@ref": "classes/spells/181388642088911360" },
    "class": { "@ref": "classes/spells" },
    "ts": 1509244539235128,
    "data": {
      "name": "Hippo's Wallow",
      "element": [ "water", "earth" ]
    }
  }
]

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

Keyboard shortcuts

While reading

While searching

URL fragments