collection.definition

We recommend you use FSL to create and update user-defined collections. See Collection schema.

Get or update a collection’s definition, represented as a Collection document.

Signature

<Collection>.definition: CollectionDef

Description

The definition property is a collection’s schema, represented as a Collection document. The document is an FQL definition of the FSL collection schema.

Definition properties

You can use dot or bracket notation to access specific fields in the definition. See Access definition properties.

Definition methods

The definition property supports several methods for managing a collection’s definition. See Methods.

Return value

Type Description

CollectionDef

Definition for the collection, represented as a Collection document.

Examples

Basic example

// Get the definition for
// the `Customer` collection.
Customer.definition
{
  name: "Customer",
  coll: Collection,
  ts: Time("2099-10-03T21:14:20.573Z"),
  migrations: [
    {
      add_wildcard: {}
    }
  ],
  wildcard: "Any",
  document_ttls: true,
  indexes: {
    byEmail: {
      terms: [
        {
          field: ".email",
          mva: false
        }
      ],
      queryable: true,
      status: "complete"
    }
  },
  computed_fields: {
    cart: {
      body: "(customer) => Order.byCustomerAndStatus(customer, \"cart\").first()",
      signature: "Order?"
    },
    orders: {
      body: "(customer) => Order.byCustomer(customer)",
      signature: "Set<Order>"
    }
  },
  fields: {
    name: {
      signature: "String"
    },
    email: {
      signature: "String"
    },
    address: {
      signature: "{ street: String, city: String, state: String, postalCode: String, country: String }"
    }
  },
  constraints: [
    {
      unique: [
        {
          field: ".email",
          mva: false
        }
      ],
      status: "active"
    }
  ],
  ttl_days: 10,
  history_days: 0
}

Access definition properties

Use dot or bracket notation to access specific fields in the definition:

// Access `computed_fields` definitions for
// the `Customer` collection.
Customer.definition.computed_fields
// Only returns computed field definitions.
{
  cart: {
    body: "(customer) => Order.byCustomerAndStatus(customer, \"cart\").first()",
    signature: "Order?"
  },
  orders: {
    body: "(customer) => Order.byCustomer(customer)",
    signature: "Set<Order>"
  }
}

Methods

The definition property supports several methods for managing a collection’s definition. Using these methods is equivalent to making an unstaged schema change.

collection.definition.delete()

Deletes a collection definition.

Signature

delete() => NullCollectionDef

Parameters

None.

Return value

Type Description

NullCollectionDef

Represents a CollectionDef document that doesn’t exist.

Examples

Customer.definition.delete()
Collection.byName("Customer") /* deleted */

collection.definition.exists()

Returns true if the collection exists. Otherwise, returns an error with the unbound_variable error code.

Signature

exists() => true

Parameters

None.

Return value

Type Description

true

Indicates the collection exists.

Examples

// The `Customer` collection exists.
Customer.definition.exists()
true

For a collection that doesn’t exist:

// The `Foo` collection doesn't exist.
Foo.definition.exists()
invalid_query: The query failed 1 validation check

error: Unbound variable `Foo`
at *query*:2:1
  |
2 | Foo.definition.exists()
  | ^^^
  |

collection.definition.replace()

Replaces a collection definition.

Signature

replace(data: { *:Any }) => CollectionDef

Parameters

Parameter Type Required Description

data

Object containing valid Collection document fields.

Yes

The replacement collection definition, represented as a Collection document. Fields not present, except immutable metadata fields, are removed.

Return value

Type Description

CollectionDef

Definition for the updated collection, represented as a Collection document.

Examples

Customer.definition.replace({
  history_days: 0,
  migrations: [
    {
      add_wildcard: {}
    }
  ],
  computed_fields: {
    cart: {
      body: "(customer) => Order.byCustomerAndStatus(customer, \"cart\").first()",
      signature: "Order?"
    },
    orders: {
      body: "(customer) => Order.byCustomer(customer)",
      signature: "Set<Order>"
    }
  },
  wildcard: "Any",
  constraints: [
    {
      unique: [
        {
          field: ".email",
          mva: false
        }
      ],
      status: "active"
    }
  ],
  indexes: {
    byEmail: {
      terms: [
        {
          field: ".email",
          mva: false
        }
      ],
      queryable: true,
      status: "complete"
    }
  },
  document_ttls: true,
  ttl_days: 10,
  fields: {
    name: {
      signature: "String"
    },
    email: {
      signature: "String"
    },
    address: {
      signature: "{ street: String, city: String, state: String, postalCode: String, country: String }"
    }
  }
})
{
  name: "Customer",
  coll: Collection,
  ts: Time("2099-10-03T21:50:53.550Z"),
  migrations: [
    {
      add_wildcard: {}
    }
  ],
  indexes: {
    byEmail: {
      terms: [
        {
          field: ".email",
          mva: false
        }
      ],
      queryable: true,
      status: "complete"
    }
  },
  constraints: [
    {
      unique: [
        {
          field: ".email",
          mva: false
        }
      ],
      status: "active"
    }
  ],
  wildcard: "Any",
  ttl_days: 10,
  computed_fields: {
    cart: {
      body: "(customer) => Order.byCustomerAndStatus(customer, \"cart\").first()",
      signature: "Order?"
    },
    orders: {
      body: "(customer) => Order.byCustomer(customer)",
      signature: "Set<Order>"
    }
  },
  fields: {
    name: {
      signature: "String"
    },
    email: {
      signature: "String"
    },
    address: {
      signature: "{ street: String, city: String, state: String, postalCode: String, country: String }"
    }
  },
  history_days: 0,
  document_ttls: true
}

collection.definition.update()

Updates a collection definition.

Signature

update(data: { *:Any }) => CollectionDef

Parameters

Parameter Type Required Description

data

Object containing valid Collection document fields.

Yes

The replacement collection definition, represented as a Collection document.

During the update, fields from the object are copied to the document, creating new fields or updating existing fields. The operation is similar to a merge.

Only the fields included in the Object are updated, all other document fields aren’t updated. Fields with nested Objects in the Object are merged with the identically named nested Object in the document.

Return value

Type Description

CollectionDef

Definition for the updated collection, represented as a Collection document.

Examples

Customer.definition.update({
  ttl_days: 15
})
{
  name: "Customer",
  coll: Collection,
  ts: Time("2099-10-03T21:50:53.550Z"),
  migrations: [
    {
      add_wildcard: {}
    }
  ],
  indexes: {
    byEmail: {
      terms: [
        {
          field: ".email",
          mva: false
        }
      ],
      queryable: true,
      status: "complete"
    }
  },
  constraints: [
    {
      unique: [
        {
          field: ".email",
          mva: false
        }
      ],
      status: "active"
    }
  ],
  wildcard: "Any",
  ttl_days: 15,
  computed_fields: {
    cart: {
      body: "(customer) => Order.byCustomerAndStatus(customer, \"cart\").first()",
      signature: "Order?"
    },
    orders: {
      body: "(customer) => Order.byCustomer(customer)",
      signature: "Set<Order>"
    }
  },
  fields: {
    name: {
      signature: "String"
    },
    email: {
      signature: "String"
    },
    address: {
      signature: "{ street: String, city: String, state: String, postalCode: String, country: String }"
    }
  },
  history_days: 0,
  document_ttls: true
}

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!