Define relationships

Relationships establish associations between documents in two or more collections. In Fauna, you create relationships by referencing one document in another.

Fauna supports the following relationship types:

Relationship type Example

one-to-one

A book has one author.

one-to-many

An author writes many books.

many-to-many

A reader has many books, and a book has many readers.

This tutorial shows how you can create relationships between documents in Fauna. The examples use Fauna’s demo data.

References and projection

When you include a document in another document’s field, Fauna stores the value as a reference. By default, this reference is returned instead of the document itself.

For example, the following Product document’s store field contains a reference to another document:

{
  id: "394062089570746432",
  coll: Product,
  ...
  name: "pizza",
  description: "Frozen Cheese",
  ...
  store: Store("394062089566552128"),
  ...
}

Use projection to resolve the reference and return the store document. For example:

// Use projection to return `name`, `desciption`, and `store` fields
Product.byName("pizza").first() {
  name,
  description,
  store {
    id,
    name,
    address
  }
}

Response with the resolved store reference:

{
  name: "pizza",
  description: "Frozen Cheese",
  store: {
    id: "394062089566552128",
    name: "Foggy Bottom Market",
    address: {
      street: "4 Florida Ave",
      city: "Washington",
      state: "DC",
      zipCode: "20037"
    }
  }
}

Create a one-to-one relationship

A one-to-one relationship exists when a document in one collection has only one associated document in another collection.

In the following example, each product is associated with one store.

// Get a store
let store = Store.byName("DC Fruits").first()

// Create a product that references the store
Product.create({
 name: "limes",
 description: "Organic, 1 ct",
 store: store
// Return the product `name`, `description`, and resolved `store`
}) { name, description, store }

Create a one-to-many relationship

A one-to-many relationship exists when a document in a collection is associated with one or more documents in the another collection.

For example, one store may be associated with multiple products.

// Get a store
let store = Store.byName("DC Fruits").first()

// Define multiple products that reference the store
let products = [
 { name: "limes", description: "Organic, 2 ct", store: store },
 { name: "limes", description: "Organic, 3 ct", store: store }
]

// Create each product
products.map(product => Product.create({
  product
// Return the product `name`, `description`, and resolved `store`
})) { name, description, store }

Create many-to-many relationships

A many-to-many relationship exists when a document in one collection is associated with multiple other documents in another collection, and vice versa.

For example, a customer can order several products. A product can also be ordered by several customers.

In Fauna, creating a many-to-many relationship requires a third collection to track the associations.

In the following example, the Order collection tracks relationships between Product and Customer documents.

// Define customer data
let customerData = [
  { firstName: "Dan", lastName: "Doe" },
  { firstName: "Evie", lastName: "Ewin" },
]

// Define product data
let productData = [
  { name: "key limes", description: "Conventional, 2 ct" },
  { name: "key limes", description: "Conventional, 3 ct" },
]

// Create customers and products
let customers = customerData.map(data => Customer.create(data))
let products = productData.map(data => Product.create(data))

// Create orders for each customer and product
customers.flatMap(customer =>
  products.map(product =>
    Order.create({
      customer: customer,
      cart: [{ product: product }]
    })
  )
// Return the resolved `customer` and `cart` for each order
) { customer, cart }

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!