Ref( schema_ref, document_id )
Ref( schema_ref, document_id )
Ref( schema_ref, document_id )
Ref( schema_ref, document_id )
ref( schema_ref, document_id )
Ref( schema_ref, document_id )


The Ref function is used to express the reference for a specific document that exists in the current database, within the schema_ref, having the document ID document_id.

References serve the same purpose as primary keys in other database systems: they are used to provide a pointer to a specific document.

The schema_ref is a reference to a specific collection of documents. Everything in Fauna is described by a document. The documents that describe fundamental Fauna infrastructure are called schema documents, or core schemas. Any other documents are user-created, and are called user documents.

References to core schema documents, that you pass in via schema_ref, are provided by their respective functions:

The Ref function does not verify that the schema_ref, or the document_id within the schema_ref, exists. This means that you can use Ref to create a reference to a non-existent document in a non-existent collection.

This feature is particularly useful when creating parent-child relationships. The parent record can be created with a list of non-existent child references before the child records are created.

You have to use this feature carefully or queries that use such references could fail.


Parameter Type Definition and Requirements


A Reference to a specific schema document to which the desired document belongs.


A document identifier, which is a string-encoded 64-bit integer.


A reference to the document in the specified schema_ref that has the specified document_id.


The following query returns the reference to a specific document in the "spells" collection:

    Value result = await client.Query(
        Ref(Collection("spells"), "181388642046968320")
catch (Exception e)
    Console.WriteLine($"ERROR: {e.Message}");
RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections")))
result, err := client.Query(
	f.Ref(f.Collection("spells"), "181388642046968320"))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
{181388642046968320 0xc000160150 0xc000160150 <nil>}
        Ref(Collection("spells"), "181388642046968320")
ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections")))
  q.Ref(q.Collection('spells'), '181388642046968320')
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',,
Ref(Collection("spells"), "181388642046968320")
result = client.query(
  q.ref(q.collection("spells"), "181388642046968320")
Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections)))
Ref(Collection('spells'), '181388642046968320')
Ref(Collection("spells"), "181388642046968320")
Query metrics:
  •    bytesIn:  57

  •   bytesOut: 130

  • computeOps:   1

  •    readOps:   0

  •   writeOps:   0

  •  readBytes:   0

  • writeBytes:   0

  •  queryTime: 7ms

  •    retries:   0

Is this article helpful? 

Tell Fauna how the article can be improved:
Visit Fauna's forums or email

Thank you for your feedback!