Database entity syntax

This section covers the FSL reference syntax for the supported database entities:

Basic syntax

FSL definitions must be encoded using the following syntactic rules.

Comments

FSL supports single-line and block comments as described in the FQL language reference.

Schema element reference

Schema elements can reference other schema elements. An example is a role that references an index or collection. An FSL reference references another schema element by name, provided the referenced element is in the same schema definition. In this example, a role named MyRole references a collection named MyCol:

collection MyCol { ... }

role MyRole {
  privileges MyCol { read }
}

Property definition

Property definition syntax has one of the following forms:

Syntax Description

<property> <value>

Sets the property value for the item.

<property> <reference>

Relationship between the enclosing schema item and the referenced item, indicating existence.

<property> <reference> { <configurationk> }

Relationship between the enclosing schema item and the referenced item, indicating existence and given a value.

Properties can be unique for a schema item or can be repeated.

access provider

An AccessProvider definition that defines the name of the access provider.

Syntax

access provider <name> {
  issuer "<issuer URL>"
  jwks_uri "<jwks URI>"
  [role <role reference> | <property> <reference> { <configuration> } . . .]
  [ttl "<time to live>"]
}

Properties

issuer String Required

The issuer URL. This tells Fauna which IdP is permitted to send a JWT to authorize a query to be executed.

jwks_uri String Required

The jwks_uri URL. This is the URL to the JSON Web Key Set endpoint that has the public key managed by the IdP that services, such as Fauna, can use to verify or decrypt a JWT and confirm its validity. The standard convention is that this URL is the issuer URL with .well-known/jwks.json appended.

role String

Role references, defined as <property> <reference>, or <property> <reference> { <configuration> } with a <configuration> predicate. The predicate must be in long form syntax. See Anonymous functions.

Examples

access provider ExampleAP {
  issuer "https://some-issuer.com"
  jwks_uri "https://some-issuer.com/.well-known/jwks.json"

  role SomeRole
  role AnotherRole {
    // the predicate is passed the JWT fields
    predicate (jwt => jwt.admin == true)
  }

collection, index, constraint

A Collection definition that defines the name of the collection.

Syntax

collection <name> {
  [history_days <history days>]
  [ttl_days <time to live days>]
  [index <index name> <index config block> . . .]
  [unique <unique constraint fields> . . .]
}

Properties

history_days Int

Number of days of document history to maintain for all documents in the collection. See Temporality.

ttl_days Int

Number of days that documents in the collection should be retained. See Temporality.

index String

See index.

unique String

See unique constraint.

index

An index definition in an FSL collection, index, constraint definition that defines the name of the index.

The index definition has the following syntax and properties:

index <name> {
  [terms [<term> . . .]]
  [values [<value> . . .]]
}

term Array

Array of field paths. An empty array leaves the field unset. See Indexes definition for defining ascending or descending order and multivalued attribute (MVA) flag.

value Array

A discrete value or range of values to match on. See Indexes definition for defining ascending or descending order and multivalued attribute (MVA) flag.

Examples:

index MyIndex {
  terms [.a.foo, .b, mva(.c.bar)]
  values [asc(.x), desc(mva(.y)), .z]
}

unique constraint

A unique constraints in an FSL collection definition that defines the unique constraints.

The unique constraint definition has the following syntax and properties:

unique [<constraintTerm> . . .]

constraintTerm Array Required

Array of field paths. See Unique constraints definition

Examples:

unique [.a.foo, .b, .c.bar]

Examples

collection Example {
  history_days 3
  ttl_days 5

  index anIndex {
    // at least one of terms or values must be provided
    terms [.path.to.field]
    values [.field1, desc(.field2), asc(.field3), desc(mva(.field4))]
  }

  unique [.field1, mva(.arrField)]
}

function

A Function definition that defines the name of the function, the function parameters, function body, and return type.

Syntax

function <name> (<parameter>: <parameterType>): <returnType> {
  <functionBody>
}

Properties

parameter String

functionBody parameter.

parameterType String

parameter type.

returnType String

functionBody return type.

functionBody String

FQL block.

Examples

function MyFunction(x: Number): Number {
  x + 2
}

role

A Role definition that defines the name of the role.

Syntax

role <name> {
  [privileges <reference> <privilegeDef> [. . .]]
  [membership <reference> <membershipDef> [. . .]]
}

Properties

privileges Object

Zero or more privilege definitions in the form:

<reference> { <privilegeDef> }

where,

<privilegeDef> ::= <action> [{ predicate (<predicateLambda>) }]

A privilege definition action is one of create, delete, read, write, and call.

The privilegeDef can be a categorical membership, such as { read; create }, or a predicate lambda.

The predicateLambda syntax depends on the action. If the predicate is omitted, the privilege for the action is granted.

The predicateLambda must be in long form syntax. See Anonymous functions.

membership String

Zero or more membershipDef membership definitions in one of the following forms:

Syntax Membership evaluation

<reference>

Categorical membership.

<reference> <predicateLambda>

A predicate that evaluates resource membership for the role.

The predicateLambda must be in long form syntax. See Anonymous functions.

Examples

role MyRole {
  privileges MyCol { read; create }
  privileges YourCol {
    read
    create
    write {
      predicate ((x, y) => {
        foo(x) - bar(y) == 2
      })
    }
  }
  membership HisCol
  }
}

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!