Model relationships using document references

collection Product {
  ...
  // The `category` field accepts a reference to
  // a `Category` collection document.
  category: Ref<Category>
  ...
}

// Get a `Category` collection document.
let produce = Category.byName("produce").first()

// Create a `Product` document that references
// the `Category` document.
Product.create({
  name: "key lime",
  description: "Organic, 1 ct",
  price: 79,
  // The `category` field includes a reference to
  // the `Category` document as a field value.
  category: produce,
  stock: 2000
})

// An example `Product` collection document.
{
  id: "412568482109981184",
  coll: Product,
  ts: Time("2099-10-23T20:20:15.150Z"),
  name: "key lime",
  description: "Organic, 1 ct",
  price: 79,
  // A `Category` document reference.
  category: Category("789"),
  stock: 2000
}

// Document reference in
// the simple format.
"category": {
  "id": "111",
  "coll": "Category"
}

# INCORRECT:
# The following request does NOT create
# a document reference. Instead, it sets
# the `category` field value to an object.
curl -X POST \
"https://db.fauna.com/query/1" \
-H "Authorization: Bearer $FAUNA_SECRET" \
-H "Content-Type: application/json" \
-H "X-Format: simple" \
-d '{
  "query": "Product.byName(\"limes\").first()?.update({ \"category\": { \"id\": \"111\", \"coll\": \"Category\" } })"
}'

collection Order {
  ...
  // The `items` field accepts an Array of references to
  // `OrderItem` collection documents.
  items: Array<Ref<OrderItem>>
  ...
}

collection Customer {
  ...
  // Defines the `preferences` object field.
  preferences: {
    // Defines the nested `store` field.
    // The `store` field accepts a reference to
    // a `Store` collection document.
    store: Ref<Store>,
    emailList: Boolean,
    ...
  }
  ...
}

collection Customer {
  ...
  // Computed field definition for the `orders` field.
  // `orders` contains a reference to a Set of `Order` collection documents.
  // The value is computed using the `Order` collection's
  // `byCustomer()` index to get the customer's orders.
  compute orders: Set<Order> = ( customer => Order.byCustomer(customer))
  ...
}

collection Customer {
  ...
  // Computed field definition for the `cart` field.
  // `cart` contains an `Order` collection document.
  // The value is computed using the `Order` collection's
  // `byCustomerAndStatus()` index to get the first order
  // for the customer with a `cart` status.
  compute cart: Order? = (customer => Order.byCustomerAndStatus(customer, 'cart').first())
  ...
}

// Products have a one-to-one relationships with
// its category. Each product has one category.

// Get a `Category` collection document
let produce = Category.byName("produce").first()

// Create a `Product` document
// that references the `Category` document.
Product.create({
 name: "key lime",
 description: "Organic, 1 ct",
 price: 79,
 category: produce,
 stock: 2000
}) { name, description, category }

// Categories have a one-to-many relationship with
// products. A category can be assigned to multiple
// products.

// Get a `Category` collection document
let produce = Category.byName("produce").first()

// Define an Array that contains data for
// multiple `Product` documents. Each `Product`
// document references the previous `Category` document.
let products = [
  {
    name: "key limes",
    description: "Organic, 2 ct",
    price: 1_39,
    // `category` contains the `Category` document reference.
    category: produce,
    stock: 1000
  },
  {
    name: "lemons",
    description: "Organic, 3 ct",
    price: 1_39,
    category: produce,
    stock: 1000
  }
]

// Use `map()` to create `Product` documents
// from the previous Array.
products.map(product => Product.create({
  product
    // Project `name`, `description`, and resolved
    // `category` fields of the `Product` documents.
})) { name, description, category }

// The `OrderItem` collection creates many-to-many
// relationships between `Order` and `Product` documents.
// A product can be included with multiple orders.
// An order can contain multiple products.
collection OrderItem {
  order: Ref<Order>
  product: Ref<Product>
  quantity: Int

  unique [.order, .product]
}

// Defines data for `Order` collection documents.
let orderData = [
  {
    customer: Customer.byId('111'),
    status: "processing",
    createdAt: Time.now()
  },
  {
    customer: Customer.byId('222'),
    status: "processing",
    createdAt: Time.now()
  }
]

// Defines data for `Product` collection documents.
let productData = [
  {
    name: "kiwis",
    description: "Organic, 2 ct",
    price: 2_39,
    // `category` contains the `Category` document reference.
    category: Category.byName("produce").first(),
    stock: 1000
  },
  {
    name: "oranges",
    description: "Organic, 3 ct",
    price: 3_39,
    category: Category.byName("produce").first(),
    stock: 1000
  }
]

// Creates `Order` and `Product` documents using
// the previous data.
let orders = orderData.map(doc => Order.create(doc))
let products = productData.map(doc => Product.create(doc))

// Create `OrderItem` documents for
// each order and product.
orders.flatMap(order =>
  products.map(product =>
    OrderItem.create({
      order: order,
      product: product,
      quantity: 1
    })
  )
// Return the resolved `order`, `product`, and `quantity`
// fields for each `OrderItem` document.
) { order, product, quantity }

// An uncovered query.
// The `category` field contains a document reference,
// which can't be covered.
Product.byCategory(Category.byId("123")) {
  category
}

// Defines the `Customer` collection.
collection Customer {
  ...
  // The `address` field contains a reference to a
  // `Address` collection document.
  address: Ref<Address>
  ....

  // INCORRECT:
  // Fauna can't index the previous `Address` document's
  // `city` field. The `city` field references another document.
  index byCity {
    terms [.address.city]
  }
}

// Defines the `Address` collection.
collection Address {
  street: String
  city: String
}

// Defines the `Customer` collection.
collection Customer {
  ...
  // The `address` field contains a reference to a
  // `Address` collection document.
  address: Ref<Address>
  ....

  // The `city` computed field gets the previous
  // `Address` document's `city` field.
  compute city = ((customer) => customer.address.city)

  // INCORRECT:
  // Fauna can't index the computed `city` field.
  // The field references another document.
  index byCity {
    terms [.city]
  }
}

collection Address {
  street: String
  city: String
}

// Defines the `Product` collection.
collection Product {
  // The `category` field contains a reference to
  // a `Category` document.
  category: Ref<Category>

  // CORRECT:
  index byCategory {
    terms [.category]
  }

  // INCORRECT:
  // Fauna can't index the previous `Category` document's `id` field.
  index byCategoryId {
    terms [.category.id]
  }
}