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

Fauna accounts created after August 21, 2024 must use FQL v10. These accounts will not be able to run FQL v4 queries or access the v4 Dashboard.

For more details, see the v4 EOL announcement and migration guide. Contact support@fauna.com with any questions.

Indexes

Problem

You need to query an index within the current database.

Solution

The Match function is used to find matching entries in an index.

Indexes created without specifying the terms field return all indexed values on the indexed collection:

client.query(
  q.Paginate(q.Match(q.Index('all_people')))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  data: [
    [
      'Alan',
      'Perlis',
      Ref(Collection("People"), "310011992898273792")
    ],
    [
      'Alan',
      'Turing',
      Ref(Collection("People"), "310011992901419520")
    ],
    [
      'Grace',
      'Hopper',
      Ref(Collection("People"), "310011992897225216")
    ],
    [
      'Leslie',
      'Lamport',
      Ref(Collection("People"), "310011992895129088")
    ],
    [
      'Marvin',
      'Minsky',
      Ref(Collection("People"), "310011992895128064")
    ],
    [
      'Stephen',
      'Cook',
      Ref(Collection("People"), "310011992891983360")
    ],
    [ 'Tim', 'Cook', Ref(Collection("People"), "310011992891982336") ]
  ]
}

result = client.query(
  q.paginate(q.match(q.index("all_people")))
)
print(result)

{'data': [['Alan', 'Perlis', Ref(id=310013802959603200, collection=Ref(id=People, collection=Ref(id=collections)))], ['Alan', 'Turing', Ref(id=310013802959602176, collection=Ref(id=People, collection=Ref(id=collections)))], ['Grace', 'Hopper', Ref(id=310013802957505024, collection=Ref(id=People, collection=Ref(id=collections)))], ['Leslie', 'Lamport', Ref(id=310013802956457472, collection=Ref(id=People, collection=Ref(id=collections)))], ['Marvin', 'Minsky', Ref(id=310013802956456448, collection=Ref(id=People, collection=Ref(id=collections)))], ['Stephen', 'Cook', Ref(id=310013802953310720, collection=Ref(id=People, collection=Ref(id=collections)))], ['Tim', 'Cook', Ref(id=310013802953311744, collection=Ref(id=People, collection=Ref(id=collections)))]]}

result, err := client.Query(
	f.Paginate(f.Match(f.Index("all_people"))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:[[Alan Perlis {310014288737600000 0xc000180570 0xc000180570 <nil>}] [Alan Turing {310014288735502848 0xc000180720 0xc000180720 <nil>}] [Grace Hopper {310014288734454272 0xc0001808d0 0xc0001808d0 <nil>}] [Leslie Lamport {310014288732357120 0xc000180a80 0xc000180a80 <nil>}] [Marvin Minsky {310014288731308544 0xc000180c30 0xc000180c30 <nil>}] [Stephen Cook {310014288729211392 0xc000180de0 0xc000180de0 <nil>}] [Tim Cook {310014288729212416 0xc000180f90 0xc000180f90 <nil>}]]]

try
{
    Value result = await client.Query(
        Paginate(Match(Index("all_people")))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(data: Arr(Arr(StringV(Alan), StringV(Perlis), RefV(id = "310141133713834496", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(StringV(Alan), StringV(Turing), RefV(id = "310141133716980224", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(StringV(Grace), StringV(Hopper), RefV(id = "310141133720125952", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(StringV(Leslie), StringV(Lamport), RefV(id = "310141133724320256", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(StringV(Marvin), StringV(Minsky), RefV(id = "310141133728514560", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(StringV(Stephen), StringV(Cook), RefV(id = "310141133731660288", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(StringV(Tim), StringV(Cook), RefV(id = "310141133734806016", collection = RefV(id = "People", collection = RefV(id = "collections"))))))

System.out.println(
    client.query(
        Paginate(Match(Index("all_people")))
    ).get());

{data: [["Alan", "Perlis", ref(id = "310136466189582848", collection = ref(id = "People", collection = ref(id = "collections")))], ["Alan", "Turing", ref(id = "310136466193777152", collection = ref(id = "People", collection = ref(id = "collections")))], ["Grace", "Hopper", ref(id = "310136466196922880", collection = ref(id = "People", collection = ref(id = "collections")))], ["Leslie", "Lamport", ref(id = "310136466201117184", collection = ref(id = "People", collection = ref(id = "collections")))], ["Marvin", "Minsky", ref(id = "310136466205311488", collection = ref(id = "People", collection = ref(id = "collections")))], ["Stephen", "Cook", ref(id = "310136466210554368", collection = ref(id = "People", collection = ref(id = "collections")))], ["Tim", "Cook", ref(id = "310136466214748672", collection = ref(id = "People", collection = ref(id = "collections")))]]}

Paginate(Match(Index('all_people')))

{
  data: [
    [
      'Alan',
      'Perlis',
      Ref(Collection("People"), "309934841578653184")
    ],
    [
      'Alan',
      'Turing',
      Ref(Collection("People"), "309934841578652160")
    ],
    [
      'Grace',
      'Hopper',
      Ref(Collection("People"), "309934841576555008")
    ],
    [
      'Leslie',
      'Lamport',
      Ref(Collection("People"), "309934841575507456")
    ],
    [
      'Marvin',
      'Minsky',
      Ref(Collection("People"), "309934841575506432")
    ],
    [
      'Stephen',
      'Cook',
      Ref(Collection("People"), "309934841572360704")
    ],
    [ 'Tim', 'Cook', Ref(Collection("People"), "309934841572361728") ]
  ]
}

Query metrics:

bytesIn: 56
bytesOut: 979
computeOps: 1
readOps: 8
writeOps: 0
readBytes: 602
writeBytes: 0
queryTime: 16ms
retries: 0

Results from index matches use a specific sorting precedence. The following example uses an index that sorts by age descending:

client.query(
  q.Paginate(q.Match(q.Index('people_by_age_desc')))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  data: [
    [
      119,
      'Grace',
      'Hopper',
      Ref(Collection("People"), "310012262298419712")
    ],
    [
      107,
      'Alan',
      'Turing',
      Ref(Collection("People"), "310012262299469312")
    ],
    [
      97,
      'Alan',
      'Perlis',
      Ref(Collection("People"), "310012262299468288")
    ],
    [
      92,
      'Marvin',
      'Minsky',
      Ref(Collection("People"), "310012262295273984")
    ],
    [
      81,
      'Stephen',
      'Cook',
      Ref(Collection("People"), "310012262292129280")
    ],
    [
      80,
      'Leslie',
      'Lamport',
      Ref(Collection("People"), "310012262296322560")
    ],
    [
      59,
      'Tim',
      'Cook',
      Ref(Collection("People"), "310012262292128256")
    ]
  ]
}

result = client.query(
  q.paginate(q.match(q.index("people_by_age_desc")))
)
print(result)

{'data': [[119, 'Grace', 'Hopper', Ref(id=310013488491660800, collection=Ref(id=People, collection=Ref(id=collections)))], [107, 'Alan', 'Turing', Ref(id=310013488494805504, collection=Ref(id=People, collection=Ref(id=collections)))], [97, 'Alan', 'Perlis', Ref(id=310013488495854080, collection=Ref(id=People, collection=Ref(id=collections)))], [92, 'Marvin', 'Minsky', Ref(id=310013488490611200, collection=Ref(id=People, collection=Ref(id=collections)))], [81, 'Stephen', 'Cook', Ref(id=310013488487466496, collection=Ref(id=People, collection=Ref(id=collections)))], [80, 'Leslie', 'Lamport', Ref(id=310013488491659776, collection=Ref(id=People, collection=Ref(id=collections)))], [59, 'Tim', 'Cook', Ref(id=310013488487465472, collection=Ref(id=People, collection=Ref(id=collections)))]]}

result, err := client.Query(
	f.Paginate(f.Match(f.Index("people_by_age_desc"))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:[[119 Grace Hopper {310014288734454272 0xc0001099b0 0xc0001099b0 <nil>}] [107 Alan Turing {310014288735502848 0xc000109b60 0xc000109b60 <nil>}] [97 Alan Perlis {310014288737600000 0xc000109d10 0xc000109d10 <nil>}] [92 Marvin Minsky {310014288731308544 0xc000109ec0 0xc000109ec0 <nil>}] [81 Stephen Cook {310014288729211392 0xc00016e090 0xc00016e090 <nil>}] [80 Leslie Lamport {310014288732357120 0xc00016e240 0xc00016e240 <nil>}] [59 Tim Cook {310014288729212416 0xc00016e3f0 0xc00016e3f0 <nil>}]]]

try
{
    Value result = await client.Query(
        Paginate(Match(Index("people_by_age_desc")))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(data: Arr(Arr(LongV(119), NullV, StringV(Hopper), RefV(id = "310141133720125952", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(LongV(107), NullV, StringV(Turing), RefV(id = "310141133716980224", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(LongV(97), NullV, StringV(Perlis), RefV(id = "310141133713834496", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(LongV(92), NullV, StringV(Minsky), RefV(id = "310141133728514560", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(LongV(81), NullV, StringV(Cook), RefV(id = "310141133731660288", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(LongV(80), NullV, StringV(Lamport), RefV(id = "310141133724320256", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(LongV(59), NullV, StringV(Cook), RefV(id = "310141133734806016", collection = RefV(id = "People", collection = RefV(id = "collections"))))))

System.out.println(
    client.query(
        Paginate(Match(Index("people_by_age_desc")))
    ).get());

{data: [[119, "Grace", "Hopper", ref(id = "310136723542639104", collection = ref(id = "People", collection = ref(id = "collections")))], [107, "Alan", "Turing", ref(id = "310136723538444800", collection = ref(id = "People", collection = ref(id = "collections")))], [97, "Alan", "Perlis", ref(id = "310136723535299072", collection = ref(id = "People", collection = ref(id = "collections")))], [92, "Marvin", "Minsky", ref(id = "310136723566756352", collection = ref(id = "People", collection = ref(id = "collections")))], [81, "Stephen", "Cook", ref(id = "310136723571999232", collection = ref(id = "People", collection = ref(id = "collections")))], [80, "Leslie", "Lamport", ref(id = "310136723546833408", collection = ref(id = "People", collection = ref(id = "collections")))], [59, "Tim", "Cook", ref(id = "310136723577242112", collection = ref(id = "People", collection = ref(id = "collections")))]]}

Paginate(Match(Index('people_by_age_desc')))

{
  data: [
    [
      119,
      'Grace',
      'Hopper',
      Ref(Collection("People"), "309995028361511424")
    ],
    [
      107,
      'Alan',
      'Turing',
      Ref(Collection("People"), "309995028357317120")
    ],
    [
      97,
      'Alan',
      'Perlis',
      Ref(Collection("People"), "309995028360462848")
    ],
    [
      92,
      'Marvin',
      'Minsky',
      Ref(Collection("People"), "309995028352074240")
    ],
    [
      81,
      'Stephen',
      'Cook',
      Ref(Collection("People"), "309995028351026688")
    ],
    [
      80,
      'Leslie',
      'Lamport',
      Ref(Collection("People"), "309995028356268544")
    ],
    [
      59,
      'Tim',
      'Cook',
      Ref(Collection("People"), "309995028351025664")
    ]
  ]
}

Query metrics:

bytesIn: 64
bytesOut: 1,002
computeOps: 1
readOps: 8
writeOps: 0
readBytes: 623
writeBytes: 0
queryTime: 131ms
retries: 0

For indexes where the terms field was defined, entries are located using the indexed terms:

client.query(
  q.Paginate(q.Match(q.Index('people_by_first'), 'Alan'))
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  data: [
    [
      'Alan',
      'Perlis',
      Ref(Collection("People"), "310012851960939008")
    ],
    [
      'Alan',
      'Turing',
      Ref(Collection("People"), "310012851957793280")
    ]
  ]
}

result = client.query(
  q.paginate(q.match(q.index("people_by_first"), "Alan"))
)
print(result)

{'data': [['Alan', 'Perlis', Ref(id=310014237971841536, collection=Ref(id=People, collection=Ref(id=collections)))], ['Alan', 'Turing', Ref(id=310014237970793984, collection=Ref(id=People, collection=Ref(id=collections)))]]}

result, err := client.Query(
	f.Paginate(f.MatchTerm(f.Index("people_by_first"), "Alan")))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:[[Alan Perlis {310014511710994944 0xc000184570 0xc000184570 <nil>}] [Alan Turing {310014511706800640 0xc000184720 0xc000184720 <nil>}]]]

try
{
    Value result = await client.Query(
        Paginate(Match(Index("people_by_first"), "Alan"))
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(data: Arr(Arr(StringV(Alan), StringV(Perlis), RefV(id = "310141133713834496", collection = RefV(id = "People", collection = RefV(id = "collections")))), Arr(StringV(Alan), StringV(Turing), RefV(id = "310141133716980224", collection = RefV(id = "People", collection = RefV(id = "collections"))))))

System.out.println(
    client.query(
        Paginate(
            Match(
                Index("people_by_first"),
                Value("Alan")
            )
        )
    ).get());

{data: [[null, null, ref(id = "310136723535299072", collection = ref(id = "People", collection = ref(id = "collections")))], [null, null, ref(id = "310136723538444800", collection = ref(id = "People", collection = ref(id = "collections")))]]}

Paginate(Match(Index('people_by_first'), 'Alan'))

{
  data: [
    [
      'Alan',
      'Perlis',
      Ref(Collection("People"), "309935512027660800")
    ],
    [
      'Alan',
      'Turing',
      Ref(Collection("People"), "309935512023466496")
    ]
  ]
}

Query metrics:

bytesIn: 65
bytesOut: 295
computeOps: 1
readOps: 1
writeOps: 0
readBytes: 153
writeBytes: 0
queryTime: 44ms
retries: 0

For indexes where a binding was defined in the terms field, Match works as if the binding was a normal field:

client.query(
  q.Paginate(
    q.Match(
      q.Index('people_by_fullname'),
      'Alan Turing'
    )
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  data: [
    [ 'Alan Turing', Ref(Collection("People"), "310011445570961920") ]
  ]
}

result = client.query(
  q.paginate(
    q.match(
      q.index("people_by_fullname"),
      "Alan Turing"
    )
  )
)
print(result)

{'data': [['Alan Turing', Ref(id=310013344420463104, collection=Ref(id=People, collection=Ref(id=collections)))]]}

result, err := client.Query(
	f.Paginate(
		f.MatchTerm(
			f.Index("people_by_fullname"),
			"Alan Turing",
		),
	),
)

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:[[Alan Turing {310014847404212736 0xc000092570 0xc000092570 <nil>}]]]

try
{
    Value result = await client.Query(
        Paginate(
            Match(
                Index("people_by_fullname"),
                "Alan Turing"
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(data: Arr(Arr(StringV(Alan Turing), RefV(id = "310142131057459712", collection = RefV(id = "People", collection = RefV(id = "collections"))))))

System.out.println(
    client.query(
        Paginate(
            Match(
                Index("people_by_fullname"),
                Value("Alan Turing")
            )
        )
    ).get());

{data: [["Alan Turing", ref(id = "310136466193777152", collection = ref(id = "People", collection = ref(id = "collections")))]]}

Paginate(
  Match(
    Index('people_by_fullname'),
    'Alan Turing'
  )
)

{
  data: [
    [ 'Alan Turing', Ref(Collection("People"), "313624171151098368") ]
  ]
}

Query metrics:

bytesIn: 75
bytesOut: 157
computeOps: 1
readOps: 1
writeOps: 0
readBytes: 94
writeBytes: 0
queryTime: 99ms
retries: 0

For indexes where there are multiple terms fields defined, the Match values must be expressed as an array:

client.query(
  q.Paginate(
    q.Match(
      q.Index('people_by_first_last'),
      ['Alan', 'Turing'],
    )
  )
)
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  data: [
    [
      'Alan',
      'Turing',
      Ref(Collection("People"), "310005407260082688")
    ]
  ]
}

result = client.query(
  q.paginate(
    q.match(
      q.index("people_by_first_last"),
      ["Alan", "Turing"]
    )
  )
)
print(result)

{'data': [['Alan', 'Turing', Ref(id=310013947139850752, collection=Ref(id=People, collection=Ref(id=collections)))]]}

result, err := client.Query(
	f.Paginate(
		f.MatchTerm(
			f.Index("people_by_first_last"),
			f.Arr{"Alan", "Turing"},
		),
	))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}

map[data:[[Alan Turing {310014511706800640 0xc000092570 0xc000092570 <nil>}]]]

try
{
    Value result = await client.Query(
        Paginate(
            Match(
                Index("people_by_first_last"),
                Arr("Alan", "Turing")
            )
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

ObjectV(data: Arr(Arr(StringV(Alan), StringV(Turing), RefV(id = "310141133716980224", collection = RefV(id = "People", collection = RefV(id = "collections"))))))

System.out.println(
    client.query(
        Paginate(
            Match(
                Index("people_by_first_last"),
                Arr(Value("Alan"), Value("Turing"))
            )
        )
    ).get());

{data: [["Alan", "Turing", ref(id = "310137132021711360", collection = ref(id = "People", collection = ref(id = "collections")))]]}

Paginate(
  Match(
    Index("people_by_first_last"),
    ["Alan", "Turing"]
  )
)

{
  data: [
    [
      'Alan',
      'Turing',
      Ref(Collection("People"), "309995228827222528")
    ]
  ]
}

Query metrics:

bytesIn: 81
bytesOut: 159
computeOps: 1
readOps: 1
writeOps: 0
readBytes: 94
writeBytes: 0
queryTime: 63ms
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!