Ref

Ref( schema_ref, id )
Ref( schema_ref, id )
Ref( schema_ref, id )
Ref( schema_ref, id )
ref( schema_ref, id )
Ref( schema_ref, id )

Description

The Ref function returns the reference for a specific document, based on the provided id, within a specific database, implicitly based on the schema_ref. Typically, this would be used to get the reference for a user document in a collection.

Everything in Fauna is described by a document. The documents that describe fundamental Fauna infrastructure are created by the system and are called schema documents, or core schemas. Any other documents are user-created, and are called user documents.

References are like primary keys in other database systems, in that they are used to provide a pointer to a unique document.

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

The Ref command does not verify that the schema_ref, or the 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 schema.

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

Argument Type Definition and Requirements

schema_ref

Ref

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

id

String

The identifier for the specific reference.

Returns

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

Examples

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

client.Query(
  Ref(Collection("spells"), "181388642046968320")
);
Ref(id=181388642046968320, class=Ref(id=spells, class=Ref(id=classes)))
curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{ "ref": { "class": "spells" }, "id": "181388642046968320" }'
{ "resource": { "@ref": "classes/spells/181388642046968320" } }
result, _ := client.Query(
  f.RefClass(f.Collection("spells"), "181388642046968320")
)

fmt.Println(result)
{181388642046968320 0xc0000ba680 <nil>}
System.out.println(
    client.query(
        Ref(Collection("spells"), "181388642046968320")
    ).get()
);
Ref(id=181388642046968320, class=Ref(id=spells, class=Ref(id=classes)))
client.query(
  q.Ref(q.Collection('spells'), '181388642046968320')
)
.then((ret) => console.log(ret))
Ref(Class("spells"), "181388642046968320")
print(client.query(
  q.ref(q.collection("spells"), "181388642046968320")
))
Ref(id=181388642046968320,class=Ref(id=spells,class=Ref(id=classes)))
client.query(
  Ref(Collection("spells"), "181388642046968320")
)
Ref(id=181388642046968320, class=Ref(id=spells, class=Ref(id=classes)))

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!