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.

Union

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

 
Union( group, ... )
union( group, ... )
Union( group, ... )
Union( group, ... )
Union( group, ... )
Union( group, ... )

Description

The Union function combines the results of one or more groups, which can be Arrays or Set References.

Parameters

Parameter Type Definition and Requirements

group

Array or Set Reference

One or more Arrays or Set References which should have their results OR’d together. All provided group items must be of the same type.

Returns

When group is an Array, an Array of the items that appear in any provided group.

When group is a Set Reference, a Set Reference of the items that appear in any provided group.

Examples

The following query combines the Set Reference returned by locating the search term "fire" in the index named "spells_by_element" and the Set Reference returned by locating the search term "water" in the index named "spells_by_element". The Paginate function materialized the results of the Union operation into a Page.

client.query(
  q.Paginate(
    q.Union(
      q.Match(q.Index('spells_by_element'), 'fire'),
      q.Match(q.Index('spells_by_element'), 'water'),
    )
  )
)
.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"),
    Ref(Collection("spells"), "181388642088911360")
  ]
}
result = client.query(
  q.paginate(
    q.union(
      q.match(q.index("spells_by_element"), "fire"),
      q.match(q.index("spells_by_element"), "water")
    )
  )
)
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))), Ref(id=181388642088911360, collection=Ref(id=spells, collection=Ref(id=collections)))]}
result, err := client.Query(
	f.Paginate(
		f.Union(
			f.MatchTerm(f.Index("spells_by_element"), "fire"),
			f.MatchTerm(f.Index("spells_by_element"), "water"))))

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:[{181388642046968320 0xc000164180 0xc000164180 <nil>} {181388642071085568 0xc000164330 0xc000164330 <nil>} {181388642088911360 0xc0001644e0 0xc0001644e0 <nil>}]]
try
{
    Value result = await client.Query(
        Paginate(
            Union(
                Match(Index("spells_by_element"), "fire"),
                Match(Index("spells_by_element"), "water")
            )
        )
    );
    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"))), RefV(id = "181388642088911360", collection = RefV(id = "spells", collection = RefV(id = "collections")))))
System.out.println(
    client.query(
        Paginate(
            Union(
                Match(Index("spells_by_element"), Value("fire")),
                Match(Index("spells_by_element"), Value("water"))
            )
        )
    ).get());
{data: [ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections"))), ref(id = "181388642071085568", collection = ref(id = "spells", collection = ref(id = "collections"))), ref(id = "181388642088911360", collection = ref(id = "spells", collection = ref(id = "collections")))]}
Paginate(
  Union(
    Match(Index('spells_by_element'), 'fire'),
    Match(Index('spells_by_element'), 'water'),
  )
)
{
  data: [
    Ref(Collection("spells"), "181388642046968320"),
    Ref(Collection("spells"), "181388642071085568"),
    Ref(Collection("spells"), "181388642088911360")
  ]
}
Query metrics:

  •    bytesIn: 135

  •   bytesOut: 377

  • computeOps:   1

  •    readOps:   2

  •   writeOps:   0

  •  readBytes: 211

  • writeBytes:   0

  •  queryTime: 7ms

  •    retries:   0

The following query is similar to the example above, but it returns document events instead of the index tuples.

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

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
map[data:[map[action:add document:{181388642046968320 0xc000144270 0xc000144270 <nil>} ts:1603747307070000] map[action:add document:{181388642071085568 0xc000144450 0xc000144450 <nil>} ts:1603747307070000] map[action:add document:{181388642088911360 0xc00008e210 0xc00008e210 <nil>} ts:1603747307070000]]]
try
{
    Value result = await client.Query(
        Paginate(
            Union(
                Match(Index("spells_by_element"), "fire"),
                Match(Index("spells_by_element"), "water")
            ),
            events: true
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
ObjectV(data: Arr(ObjectV(ts: LongV(1603756842880000),action: StringV(add),document: RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections")))), ObjectV(ts: LongV(1603756842880000),action: StringV(add),document: RefV(id = "181388642071085568", collection = RefV(id = "spells", collection = RefV(id = "collections")))), ObjectV(ts: LongV(1603756842880000),action: StringV(add),document: RefV(id = "181388642088911360", collection = RefV(id = "spells", collection = RefV(id = "collections"))))))
System.out.println(
    client.query(
        Paginate(
            Events(
                Union(
                    Match(Index("spells_by_element"), Value("fire")),
                    Match(Index("spells_by_element"), Value("water"))
                )
            )
        )
        .events(true)
    ).get());
{data: [{ts: 1594337952410000, action: "add", document: ref(id = "181388642046968320", collection = ref(id = "spells", collection = ref(id = "collections")))}, {ts: 1594337952410000, action: "add", document: ref(id = "181388642071085568", collection = ref(id = "spells", collection = ref(id = "collections")))}, {ts: 1594337952410000, action: "add", document: ref(id = "181388642088911360", collection = ref(id = "spells", collection = ref(id = "collections")))}]}
Paginate(
  Events(
    Union(
      Match(Index('spells_by_element'), 'fire'),
      Match(Index('spells_by_element'), 'water'),
    )
  )
)
{
  data: [
    {
      ts: 1624310551550000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320")
    },
    {
      ts: 1624310551550000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568")
    },
    {
      ts: 1624310551550000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642088911360")
    }
  ]
}
Query metrics:

  •    bytesIn: 146

  •   bytesOut: 527

  • computeOps:   1

  •    readOps:   2

  •   writeOps:   0

  •  readBytes: 211

  • writeBytes:   0

  •  queryTime: 8ms

  •    retries:   0

The following query demonstrates how various arrays are evaluated:

client.query([
  q.Union(['A', 'B'], ['C', 'D']),
  q.Union(['A', 'B'], ['B', 'C']),
  q.Union(['A', 'B', 'C'], ['B', 'C'], ['B', 'C', 'D']),
  q.Union(['A', 'B', 'C'], ['B', 'B'], ['B']),
])
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))
[ [ 'A', 'B', 'C', 'D' ],
  [ 'A', 'B', 'C' ],
  [ 'A', 'B', 'C', 'D' ],
  [ 'A', 'B', 'B', 'C' ] ]
result = client.query(
  [
    q.union(["A", "B"], ["C", "D"]),
    q.union(["A", "B"], ["B", "C"]),
    q.union(["A", "B", "C"], ["B", "C"], ["B", "C", "D"]),
    q.union(["A", "B", "C"], ["B", "B"], ["B"]),
  ]
)
print(result)
[['A', 'B', 'C', 'D'], ['A', 'B', 'C'], ['A', 'B', 'C', 'D'], ['A', 'B', 'B', 'C']]
result, err := client.Query(
	f.Arr{
		f.Union(f.Arr{"A", "B"}, f.Arr{"C", "D"}),
		f.Union(f.Arr{"A", "B"}, f.Arr{"B", "C"}),
		f.Union(f.Arr{"A", "B", "C"}, f.Arr{"B", "C"}, f.Arr{"B", "C", "D"}),
		f.Union(f.Arr{"A", "B", "C"}, f.Arr{"B", "B"}, f.Arr{"B"}),
	})

if err != nil {
	fmt.Fprintln(os.Stderr, err)
} else {
	fmt.Println(result)
}
[[A B C D] [A B C] [A B C D] [A B B C]]
try
{
    Value result = await client.Query(
        Arr(
            Union(Arr("A", "B"), Arr("C", "D")),
            Union(Arr("A", "B"), Arr("B", "C")),
            Union(Arr("A", "B", "C"), Arr("B", "C"), Arr("B", "C", "D")),
            Union(Arr("A", "B", "C"), Arr("B", "B"), Arr("B"))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}
Arr(Arr(StringV(A), StringV(B), StringV(C), StringV(D)), Arr(StringV(A), StringV(B), StringV(C)), Arr(StringV(A), StringV(B), StringV(C), StringV(D)), Arr(StringV(A), StringV(B), StringV(B), StringV(C)))
System.out.println(
    client.query(
        Arr(
            Union(
                Arr(Value("A"), Value("B")),
                Arr(Value("C"), Value("D"))
            ),
            Union(
                Arr(Value("A"), Value("B")),
                Arr(Value("B"), Value("C"))
            ),
            Union(
                Arr(Value("A"), Value("B"), Value("C")),
                Arr(Value("B"), Value("C")),
                Arr(Value("B"), Value("C"), Value("D"))
            ),
            Union(
                Arr(Value("A"), Value("B"), Value("C")),
                Arr(Value("B"), Value("B")),
                Arr(Value("B"))
            )
        )
    ).get());
[["A", "B", "C", "D"], ["A", "B", "C"], ["A", "B", "C", "D"], ["A", "B", "B", "C"]]
[
  Union(['A', 'B'], ['C', 'D']),
  Union(['A', 'B'], ['B', 'C']),
  Union(['A', 'B', 'C'], ['B', 'C'], ['B', 'C', 'D']),
  Union(['A', 'B', 'C'], ['B', 'B'], ['B'])
]
[
  [ 'A', 'B', 'C', 'D' ],
  [ 'A', 'B', 'C' ],
  [ 'A', 'B', 'C', 'D' ],
  [ 'A', 'B', 'B', 'C' ]
]
Query metrics:

  •    bytesIn: 157

  •   bytesOut:  82

  • computeOps:   1

  •    readOps:   0

  •   writeOps:   0

  •  readBytes:   0

  • writeBytes:   0

  •  queryTime: 4ms

  •    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!