FQL v4 will be decommissioned on June 30, 2025. Ensure that you complete your migration from FQL v4 to FQL v10 by that date.

For more details, review the migration guide. Contact support@fauna.com with any questions.

Match

This reference topic applies to FQL v4. Go to this page for the latest FQL v10 reference topics.

 
Match( index, [ terms ] )
match( index, [ terms ] )
Match(index)
MatchTerm(index, terms)
Match( index, [ terms ] )
Match( index, [ terms ] )

Description

The Match function finds the specified terms in the specified index. The terms must be identical to the terms in the index, including both the value of all terms and number of terms, or no matching can occur. If the index is configured with no terms, then the terms argument should be omitted. If the index is configured with multiple terms, then terms should be an Array of values.

An index only holds scalar Values, such as Numbers and Strings, and does not index Objects. Indexing an Array of scalar values results in one index entry per array item. As a result, Match can only be used to search for scalar values, and not arrays or objects. Only exact matching is provided: there is no wildcard matching available.

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.

You can call Get on the result of calling Match to retrieve the first document (based on the included index’s sort order) in the set. If the set contains no entries, Get fails with a "set not found" error.

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

Parameter 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.

terms

A single scalar Value or Array of scalar Values

Optional - The terms to locate in the index.

In order to match, terms must be identical to the index’s terms definition, including both the value of all terms and number of terms. If the index is configured with no terms, then the terms argument should be omitted. If the index is configured with multiple terms fields, then terms should be provided as an array of scalar values.

Returns

A Set Reference 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(
  q.Paginate(q.Match(q.Index('spells_by_element'), 'fire'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  data: [
    Ref(Collection("spells"), "181388642046968320"),
    Ref(Collection("spells"), "181388642071085568")
  ]
}
result = client.query(
  q.paginate(q.match(q.index("spells_by_element"), "fire"))
)
print(result)
{'data': [Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))), Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections)))]}
result, err := client.Query(
	f.Paginate(
		f.MatchTerm(f.Index("spells_by_element"), "fire")))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:[{181388642046968320 0xc00008e2d0 0xc00008e2d0 <nil>} {181388642071085568 0xc00008e480 0xc00008e480 <nil>}]]
try
{
    Value result = await client.Query(
        Paginate(Match(Index("spells_by_element"), "fire"))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(data: Arr(RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections"))), RefV(id = "181388642071085568", collection = RefV(id = "spells", collection = RefV(id = "collections")))))
Paginate(Match(Index('spells_by_element'), 'fire'))
{
  data: [
    Ref(Collection("spells"), "181388642046968320"),
    Ref(Collection("spells"), "181388642071085568")
  ]
}
Query metrics:

  •    bytesIn:  67

  •   bytesOut: 259

  • computeOps:   1

  •    readOps:   1

  •   writeOps:   0

  •  readBytes: 105

  • writeBytes:   0

  •  queryTime: 7ms

  •    retries:   0

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(
  q.Paginate(
    q.Events(q.Match(q.Index('spells_by_element'), 'fire'))
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
{
  data: [
    {
      ts: 1592113606900000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320")
    },
    {
      ts: 1592113606900000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568")
    }
  ]
}
result = client.query(
  q.paginate(
    q.match(q.index("spells_by_element"), "fire"),
    events=True
  )
)
print(result)
{'data': [{'ts': 1592936355250000, 'action': 'add', 'document': Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections)))}, {'ts': 1592936355250000, 'action': 'add', 'document': Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections)))}]}
result, err := client.Query(
	f.Paginate(
		f.Events(
			f.MatchTerm(f.Index("spells_by_element"), "fire"))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:[map[action:add document:{181388642046968320 0xc0001621b0 0xc0001621b0 <nil>} ts:1603747233890000] map[action:add document:{181388642071085568 0xc000162390 0xc000162390 <nil>} ts:1603747233890000]]]
try
{
    Value result = await client.Query(
        Paginate(
            Match(Index("spells_by_element"), "fire"),
            events: true
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(data: Arr(ObjectV(ts: LongV(1603756505480000),action: StringV(add),document: RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections")))), ObjectV(ts: LongV(1603756505480000),action: StringV(add),document: RefV(id = "181388642071085568", collection = RefV(id = "spells", collection = RefV(id = "collections"))))))
Paginate(
  Events(Match(Index('spells_by_element'), 'fire'))
)
{
  data: [
    {
      ts: 1624310468410000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320")
    },
    {
      ts: 1624310468410000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568")
    }
  ]
}
Query metrics:

  •    bytesIn:  78

  •   bytesOut: 359

  • computeOps:   1

  •    readOps:   1

  •   writeOps:   0

  •  readBytes: 105

  • writeBytes:   0

  •  queryTime: 9ms

  •    retries:   0

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!