Match

Match( index, [ search_terms ] )
Match( index, [ search_terms ] )
Match( index, [ search_terms ] )
Match( index, [ search_terms ] )
match( index, [ search_terms ] )
Match( index, [ search_terms ] )

Description

The Match function finds the "search terms" provided to Match in the requested index. The search_terms must be identical to the terms in the index, including both the value of all terms and number of terms. If the index is configured with no terms, then the search_terms argument should be omitted. If the index is configured with multiple terms, then the "search terms" should be an array of values.

When calling Match through Paginate, the results are returned as an array of pages. If no matching element is found an empty collection is returned.

If Match only returns a single document, or only the first document is needed, Get may be used to retrieve the document.

Match only finds exact matches. It cannot perform pattern matches, or check alternatives. You might find the Filter function useful for matching by other criteria.

Parameters

Argument Type Definition and Requirements

index

String or Index Reference

The name, or reference, of the index to match against. An index reference can be acquired using the Index function.

search_terms

Value or Array of values

Optional - The terms to locate in the index.

search_terms must be identical to the terms in the index, including both the value of all terms and number of terms. If the index is configured with no terms, then the search_terms argument should be omitted. If the index is configured with multiple terms fields, then search_terms should be an array of values.

Returns

A SetRef for all of the matching results.

Examples

The following query searches the index "spells_by_element" for an exact match to the search term "fire". The query is executed by calling the paginate function which returns results as a set of type page.

client.Query(
  Paginate(Match(Index("spells_by_element"), "fire")));
{
  "data": [
    { "@ref": "classes/spells/181388642046968320" },
    { "@ref": "classes/spells/181388642071085568" }
  ]
}
curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "paginate": {
            "match": { "index": "spells_by_element" },
            "terms": "fire"
          }
        }'
HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      { "@ref": "classes/spells/181388642046968320" },
      { "@ref": "classes/spells/181388642071085568" }
    ]
  }
}
result, _ := client.Query(
    f.Paginate(
        f.MatchTerm(f.Index("spells_by_element"), "fire"),
    ),
)

fmt.Println(result)
map[data:[{181388642046968320 0xc4202a8a00 <nil>} {181388642071085568 0xc4202a8c20 <nil>}]]
System.out.println(
       client.query(
         Paginate(
           Match(Index(Value("spells_by_element")), Value("fire")))
       ).get());
{
  data: [
    ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections"))),
    ref(id = "181388642071085568", collection = ref(id = "spells", collection = ref(id = "collections")))
  ]
}
client.query(
  q.Paginate(q.Match(q.Index('spells_by_element'), 'fire'))
)
.then((ret) => console.log(ret))
{ data:
   [ Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))),
     Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections))) ] }
client.query(
  q.paginate(q.match(q.index("spells_by_element"), "fire")))
{
  "data": [
    { "@ref": "classes/spells/181388642046968320" },
    { "@ref": "classes/spells/181388642071085568" }
  ]
}
client.query(
  Paginate(Match(Index("spells_by_element"), "fire")))
{
  "data": [
    { "@ref": "classes/spells/181388642046968320" },
    { "@ref": "classes/spells/181388642071085568" }
  ]
}

The events view of match contains events for document as they enter and exit the set over time, based on updates to the documents themselves.

client.Query(
  Paginate(
    Match(Index("spells_by_element"), "fire"),
    events: true));
{
  "data": [
    {
      "ts": 1509244539203043,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642046968320" }
    },
    {
      "ts": 1509244539223511,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642071085568" }
    }
  ]
}
curl https://db.fauna.com/ \
    -u fnAChGwBcAACAO70ziE0cfROosNJHdgBmJU1PgpL: \
    -d '{
          "paginate": {
            "match": { "index": "spells_by_element" },
            "terms": "fire"
          },
          "events": true
        }'
HTTP/1.1 200 OK
{
  "resource": {
    "data": [
      {
        "ts": 1509244539203043,
        "action": "create",
        "resource": { "@ref": "classes/spells/181388642046968320" }
      },
      {
        "ts": 1509244539223511,
        "action": "create",
        "resource": { "@ref": "classes/spells/181388642071085568" }
      }
    ]
  }
}
result, _ := client.Query(
    f.Paginate(
        f.Events(
            f.MatchTerm(f.Index("spells_by_element"), "fire"),
        ),
    ),
)

fmt.Println(result)
map[data:[
  map[ts:1509244539203043 action:add document:{181388642046968320 0xc420293a00 <nil>}]
  map[ts:1509244539223511 action:add document:{181388642071085568 0xc420293cc0 <nil>}]
]]
System.out.println(
        client.query(
           Paginate(
              Events(
                 Match(Index(Value("spells_by_element")), Value("fire"))
              )
           )
        ).get());
{
  data: [
    {
      ts: 1527008249876598, 
      action: "add", 
      document: ref(id = "181388642071085568", collection = ref(id = "spells", collection = ref(id = "collections")))
    }, 
    {
      ts: 1527008249889400, 
      action: "add", 
      document: ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections")))
    }
  ]
}
client.query(
  q.Paginate(
    q.Events(q.Match(q.Index('spells_by_element'), 'fire'))
  )
)
.then((ret) => console.log(ret))
{ data:
   [ { ts: 1526677776479051,
       action: 'add',
       document:
        Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))) },
     { ts: 1526677776479051,
       action: 'add',
       document:
        Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections))) } ] }
client.query(
  q.paginate(
    q.match(q.index("spells_by_element"), "fire"),
    events=True
  ))
{
  "data": [
    {
      "ts": 1509244539203043,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642046968320" }
    },
    {
      "ts": 1509244539223511,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642071085568" }
    }
  ]
}
client.query(
  Paginate(
    Match(Index("spells_by_element"), "fire"),
    events = true))
{
  "data": [
    {
      "ts": 1509244539203043,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642046968320" }
    },
    {
      "ts": 1509244539223511,
      "action": "create",
      "resource": { "@ref": "classes/spells/181388642071085568" }
    }
  ]
}

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!