Sets

Sets are sorted groups of tuples. An index derives sets from documents within the collections in its source. As documents are created, modified, and deleted, sets are updated to reflect their documents' current state.

Indexes are groups of sets, each of which has a natural key; a tuple of zero or more terms. The Match query function constructs a set ref to identify a set for a given tuple of terms within an index:

client.Query(Match(Index("spells_by_element"), "water"));
{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "water"
  }
}
curl https://db.fauna.com/ \
    -u fnACrVIrDDACAFiX3FN4PhwADpl7dtPRhWObP08j: \
    -d '{ "match": { "index": "spells_by_element" }, "terms": "water" }'
HTTP/1.1 200 OK
{
  "resource": {
    "@set": {
      "match": { "@ref": "indexes/spells_by_element" },
      "terms": "water"
    }
  }
}
result, _ := client.Query(f.MatchTerm(f.Index("spells_by_element"), "water"))

fmt.Println(result)
{map[match:{spells_by_element 0xc4202b6040 <nil>} terms:water]}
System.out.println(
   client.query(
      Match(Index(Value("spells_by_element")), Value("water"))
).get());
{
  @set = {
    match: ref(id = "spells_by_element", collection = ref(id = "indexes")), 
    terms: "water"
  }
}
client.query(q.Match(q.Index('spells_by_element'), 'water'))
.then((ret) => console.log(ret))
SetRef({"match":{"@ref":{"id":"spells_by_element","class":{"@ref":{"id":"indexes"}}}},"terms":"water"})
client.query(q.match(q.index("spells_by_element"), "water"))
{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "water"
  }
}
$client.query do
  match index('spells_by_element'), 'water'
end
{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "water"
  }
}
client.query(Match(Index("spells_by_element"), "water"))
{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "water"
  }
}
client.query(
    Match(index: Index("spells_by_element"), terms: "water")
)
{
  "@set": {
    "match": { "@ref": "indexes/spells_by_element" },
    "terms": "water"
  }
}

Set refs are unique according to their structure: Two set refs with the same structure refer to the same set within a database. Query functions such as Union, Intersection, and Join allow the construction of more complex logical set identifiers:

client.Query(
  Intersection(
    Match(Index("spells_by_element"), "water"),
    Match(Index("spells_by_element"), "fire")));
{
  "@set": {
    "intersection": [
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "water"
        }
      },
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "fire"
        }
      }
    ]
  }
}
curl https://db.fauna.com/ \
    -u fnACrVIrDDACAFiX3FN4PhwADpl7dtPRhWObP08j: \
    -d '{
          "intersection": [
            {
              "match": { "index": "spells_by_element" },
              "terms": "water"
            },
            {
              "match": { "index": "spells_by_element" },
              "terms": "fire"
            }
          ]
        }'
HTTP/1.1 200 OK
{
  "resource": {
    "@set": {
      "intersection": [
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "water"
          }
        },
        {
          "@set": {
            "match": { "@ref": "indexes/spells_by_element" },
            "terms": "fire"
          }
        }
      ]
    }
  }
}
result, _ := client.Query(
    f.Intersection(
        f.MatchTerm(f.Index("spells_by_element"), "water"),
        f.MatchTerm(f.Index("spells_by_element"), "fire"),
    ),
)

fmt.Println(result)
{map[intersection:[{map[match:{spells_by_element 0xc42026c760 <nil>} terms:water]} {map[match:{spells_by_element 0xc42026c920 <nil>} terms:fire]}]]}
System.out.println( 
    client.query(
       Intersection(
          Match(Index(Value("spells_by_element")), Value("fire")),
          Match(Index(Value("spells_by_element")), Value("water")))
    ).get());
{
  @set = {
    intersection: [
    {
      @set = {
        match: ref(id = "spells_by_element", collection = ref(id = "indexes")), 
        terms: "fire"
      }, 
      {
        @set = {
          match: ref(id = "spells_by_element", collection = ref(id = "indexes")), 
          terms: "water"
        }
      }
    ]
  }
}
client.query(
  q.Intersection(
    q.Match(q.Index('spells_by_element'), 'water'),
    q.Match(q.Index('spells_by_element'), 'fire'),
  )
)
.then((ret) => console.log(ret))
SetRef({"intersection":[{"@set":{"match":{"@ref":{"id":"spells_by_element","class":{"@ref":{"id":"indexes"}}}},"terms":"water"}},{"@set":{"match":{"@ref":{"id":"spells_by_element","class":{"@ref":{"id":"indexes"}}}},"terms":"fire"}}]})
client.query(
  q.intersection(
    q.match(q.index("spells_by_element"), "water"),
    q.match(q.index("spells_by_element"), "fire")
  ))
{
  "@set": {
    "intersection": [
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "water"
        }
      },
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "fire"
        }
      }
    ]
  }
}
$client.query do
  intersection match(index('spells_by_element'), 'water'),
               match(index('spells_by_element'), 'fire')
end
{
  "@set": {
    "intersection": [
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "water"
        }
      },
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "fire"
        }
      }
    ]
  }
}
client.query(
  Intersection(
    Match(Index("spells_by_element"), "water"),
    Match(Index("spells_by_element"), "fire")))
{
  "@set": {
    "intersection": [
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "water"
        }
      },
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "fire"
        }
      }
    ]
  }
}
client.query(
    Intersection(
        Match(
            index: Index("spells_by_element"),
            terms: "water"
        ),
        Match(
            index: Index("spells_by_element"),
            terms: "fire"
        )
    )
)
{
  "@set": {
    "intersection": [
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "water"
        }
      },
      {
        "@set": {
          "match": { "@ref": "indexes/spells_by_element" },
          "terms": "fire"
        }
      }
    ]
  }
}

The Paginate function is used to retrieve the tuples of a set. The Page object returned by Paginate contains an array of tuples and cursors for moving forward or backward within the set.

Field Type Definition and Requirements

data

Array

The elements in the page.

after

Cursor

The cursor for the next page, inclusive. Optional.

before

Cursor

The cursor for the previous page, exclusive. Optional.

Pages can be further manipulated using collection-oriented functions such as Map and Filter, or individual elements can be extracted using select.

Functions that operate on sets

All

Tests whether all of the provided values are true.
Any

Tests whether any of the provided values are true.
Count

Counts the items in an array or set.
Difference

Returns the set of items in one set that are missing from additional sets.
Distinct

Returns the set of distinct items within a set.
Events

Returns the set of events describing the history of a set or document.
Filter

Fetches specific items from a set.
Intersection

Returns the set of items that exist in all sets.
IsEmpty

Tests whether an array or set is empty.
IsNonEmpty

Tests whether an array or set contains items.
Join

Combines the items in a set with set’s indexed values.
Match

Returns the set of items that match search terms.
Max

Returns the largest value in a list of numbers.
Mean

Returns the average value of the items in an array or set.
Min

Returns the smallest value in a list of numbers.
Range

Returns a subset of a set, in the specified range.
Reduce

Reduce an array or set to a result via a lambda function.
Reverse

Reverses the order of the items in a set.
Singleton

Returns a set containing the first item of a set.
Sum

Sums the items in an array or set.
Union

Returns a set that combines the items in multiple sets.

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!