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.

`Distinct`

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

Distinct( source )

distinct( source )

Distinct( source )

Distinct( source )

Distinct( source )

Description

The Distinct function returns all of the unique items found in source, which can be an Array or Set.

The run time of Distinct is dependent on the size of the underlying set or page, and the exclusivity of the result. For large sets or pages with many non-exclusive items, executing Distinct might result in a query timeout error.

For query timeout errors, you may specify a larger query timeout via the driver that you are using.

Parameters

Parameter Type Definition and Requirements

Parameter	Type	Definition and Requirements
`source`	Array or Set Reference	The Array or Set Reference to evaluate for distinct elements.

source

Array or Set Reference

The Array or Set Reference to evaluate for distinct elements.

Returns

When source is an Array, an Array of the distinct items found in source.

When source is a Set Reference, a Set Reference of the distinct items found in source.

Examples

The following query shows all of the elements in the "elements_of_spells" index. The index contains duplicate values for "fire" and "water".

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

{
  data: [
    'air',   'air',
    'earth', 'fire',
    'fire',  'water',
    'water'
  ]
}

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

{'data': ['air', 'air', 'earth', 'fire', 'fire', 'water', 'water']}

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

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

map[data:[air air earth fire fire water water]]

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

ObjectV(data: Arr(StringV(air), StringV(air), StringV(earth), StringV(fire), StringV(fire), StringV(water), StringV(water)))

Paginate(Match(Index('elements_of_spells')))

{
  data: [
    'air',   'air',
    'earth', 'fire',
    'fire',  'water',
    'water'
  ]
}

Query metrics:

bytesIn: 64
bytesOut: 73
computeOps: 1
readOps: 8
writeOps: 0
readBytes: 466
writeBytes: 0
queryTime: 7ms
retries: 0

When the Distinct function is applied to this query, the duplicate values, "fire" and "water" are eliminated.

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

{ data: [ 'air', 'earth', 'fire', 'water' ] }

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

{'data': ['air', 'earth', 'fire', 'water']}

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

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

map[data:[air earth fire water]]

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

ObjectV(data: Arr(StringV(air), StringV(earth), StringV(fire), StringV(water)))

Paginate(Distinct(Match(Index('elements_of_spells'))))

{ data: [ 'air', 'earth', 'fire', 'water' ] }

Query metrics:

bytesIn: 77
bytesOut: 52
computeOps: 1
readOps: 8
writeOps: 0
readBytes: 466
writeBytes: 0
queryTime: 11ms
retries: 0

The events view of a set of values include the resources themselves, the distinct function returns the same set.

client.query(
  q.Paginate(
    q.Events(q.Distinct(q.Match(q.Index('elements_of_spells'))))
  )
)
.then((ret) => console.log(util.inspect(ret, { depth: null })))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

{
  data: [
    {
      ts: 1592270149090000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320"),
      data: [ 'air' ]
    },
    {
      ts: 1592270149090000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320"),
      data: [ 'fire' ]
    },
    {
      ts: 1592270149090000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568"),
      data: [ 'fire' ]
    },
    {
      ts: 1592270149090000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568"),
      data: [ 'water' ]
    },
    {
      ts: 1592270149090000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642088911360"),
      data: [ 'earth' ]
    },
    {
      ts: 1592270149090000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642088911360"),
      data: [ 'water' ]
    },
    {
      ts: 1592270149090000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642581742080"),
      data: [ 'air' ]
    }
  ]
}

result = client.query(
  q.paginate(
    q.distinct(q.match(q.index("elements_of_spells"))),
    events=True
  )
)
print(result)

{'data': [{'ts': 1592864274420000, 'action': 'add', 'document': Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))), 'data': ['air']}, {'ts': 1592864274420000, 'action': 'add', 'document': Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections))), 'data': ['fire']}, {'ts': 1592864274420000, 'action': 'add', 'document': Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections))), 'data': ['fire']}, {'ts': 1592864274420000, 'action': 'add', 'document': Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections))), 'data': ['water']}, {'ts': 1592864274420000, 'action': 'add', 'document': Ref(id=181388642088911360, collection=Ref(id=spells, collection=Ref(id=collections))), 'data': ['earth']}, {'ts': 1592864274420000, 'action': 'add', 'document': Ref(id=181388642088911360, collection=Ref(id=spells, collection=Ref(id=collections))), 'data': ['water']}, {'ts': 1592864274420000, 'action': 'add', 'document': Ref(id=181388642581742080, collection=Ref(id=spells, collection=Ref(id=collections))), 'data': ['air']}]}

result, err := client.Query(
	f.Paginate(
		f.Events(
			f.Distinct(f.Match(f.Index("elements_of_spells"))))))

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

map[data:[map[action:add data:[air] document:{181388642046968320 0xc00009a210 0xc00009a210 <nil>} ts:1603747155400000] map[action:add data:[fire] document:{181388642046968320 0xc00009a3f0 0xc00009a3f0 <nil>} ts:1603747155400000] map[action:add data:[fire] document:{181388642071085568 0xc00008e210 0xc00008e210 <nil>} ts:1603747155400000] map[action:add data:[water] document:{181388642071085568 0xc00008e3f0 0xc00008e3f0 <nil>} ts:1603747155400000] map[action:add data:[earth] document:{181388642088911360 0xc00008e5d0 0xc00008e5d0 <nil>} ts:1603747155400000] map[action:add data:[water] document:{181388642088911360 0xc00008e7b0 0xc00008e7b0 <nil>} ts:1603747155400000] map[action:add data:[air] document:{181388642581742080 0xc00008e990 0xc00008e990 <nil>} ts:1603747155400000]]]

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

ObjectV(data: Arr(ObjectV(ts: LongV(1603756252570000),action: StringV(add),document: RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections"))),data: Arr(StringV(air))), ObjectV(ts: LongV(1603756252570000),action: StringV(add),document: RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections"))),data: Arr(StringV(fire))), ObjectV(ts: LongV(1603756252570000),action: StringV(add),document: RefV(id = "181388642071085568", collection = RefV(id = "spells", collection = RefV(id = "collections"))),data: Arr(StringV(fire))), ObjectV(ts: LongV(1603756252570000),action: StringV(add),document: RefV(id = "181388642071085568", collection = RefV(id = "spells", collection = RefV(id = "collections"))),data: Arr(StringV(water))), ObjectV(ts: LongV(1603756252570000),action: StringV(add),document: RefV(id = "181388642088911360", collection = RefV(id = "spells", collection = RefV(id = "collections"))),data: Arr(StringV(earth))), ObjectV(ts: LongV(1603756252570000),action: StringV(add),document: RefV(id = "181388642088911360", collection = RefV(id = "spells", collection = RefV(id = "collections"))),data: Arr(StringV(water))), ObjectV(ts: LongV(1603756252570000),action: StringV(add),document: RefV(id = "181388642581742080", collection = RefV(id = "spells", collection = RefV(id = "collections"))),data: Arr(StringV(air)))))

Paginate(
  Events(Distinct(Match(Index('elements_of_spells'))))
)

{
  data: [
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320"),
      data: [ 'air' ]
    },
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320"),
      data: [ 'fire' ]
    },
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568"),
      data: [ 'fire' ]
    },
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568"),
      data: [ 'water' ]
    },
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642088911360"),
      data: [ 'earth' ]
    },
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642088911360"),
      data: [ 'water' ]
    },
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642581742080"),
      data: [ 'air' ]
    }
  ]
}

Query metrics:

bytesIn: 88
bytesOut: 1,312
computeOps: 1
readOps: 8
writeOps: 0
readBytes: 466
writeBytes: 0
queryTime: 10ms
retries: 0

The following query demonstrates how various arrays are evaluated:

client.query([
  q.Distinct(['A', 'B', 'C']),
  q.Distinct(['A', 'B', 'A']),
  q.Distinct(['A', 'A', 'A']),
])
.then((ret) => console.log(ret))
.catch((err) => console.error(
  'Error: [%s] %s: %s',
  err.name,
  err.message,
  err.errors()[0].description,
))

[ [ 'A', 'B', 'C' ], [ 'A', 'B' ], [ 'A' ] ]

result = client.query(
  [
    q.distinct(['A', 'B', 'C']),
    q.distinct(['A', 'B', 'A']),
    q.distinct(['A', 'A', 'A']),
  ]
)
print(result)

[['A', 'B', 'C'], ['A', 'B'], ['A']]

result, err := client.Query(
	f.Arr{
		f.Distinct(f.Arr{"A", "B", "C"}),
		f.Distinct(f.Arr{"A", "B", "A"}),
		f.Distinct(f.Arr{"A", "A", "A"}),
	})

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

[[A B C] [A B] [A]]

try
{
    Value result = await client.Query(
        Arr(
            Distinct(Arr("A", "B", "C")),
            Distinct(Arr("A", "B", "A")),
            Distinct(Arr("A", "A", "A"))
        )
    );
    Console.WriteLine(result);
}
catch (Exception e)
{
    Console.WriteLine($"ERROR: {e.Message}");
}

Arr(Arr(StringV(A), StringV(B), StringV(C)), Arr(StringV(A), StringV(B)), Arr(StringV(A)))

[
  Distinct(['A', 'B', 'C']),
  Distinct(['A', 'B', 'A']),
  Distinct(['A', 'A', 'A'])
]

[ [ 'A', 'B', 'C' ], [ 'A', 'B' ], [ 'A' ] ]

Query metrics:

bytesIn: 82
bytesOut: 44
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!

Distinct

Description

Parameters

Returns

Examples

Related functions

Keyboard shortcuts

While reading

While searching

URL fragments

`Distinct`