FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, review the migration guide. Contact support@fauna.com with any questions.

Ref

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
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 )

Description

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.

Parameters

Parameter Type Definition and Requirements

schema_ref

Reference

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

document_id

String

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

Returns

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

Examples

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

client.query(
  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(Collection("spells"), "181388642046968320")
result = client.query(
  q.ref(q.collection("spells"), "181388642046968320")
)
print(result)
Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections)))
result, err := client.Query(
	f.Ref(f.Collection("spells"), "181388642046968320"))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
{181388642046968320 0xc000160150 0xc000160150 <nil>}
try
{
    Value result = await client.Query(
        Ref(Collection("spells"), "181388642046968320")
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(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 docs@fauna.com

Thank you for your feedback!