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.

Difference

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

 
Difference( source, diff, ... )
difference( source, diff, ... )
Difference( source, diff, ... )
Difference( source, diff, ... )
Difference( source, diff, ... )

Description

The Difference function compares the source, which can be an Array or Set, with the item(s) provided by diff, and returns all of the items that exist in source that do not exist in diff.

The run time of Difference 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 Difference 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

source

Array or Set Reference

The source Array or Set Reference to be compared. The type of source must match all of the items in diff.

diff

Array or Set Reference

One or more difference Arrays or Set References. The type of all items in diff must match the type of source.

Returns

When source is an Array, an Array of the items in source that are missing from diff.

When source is a Set Reference, a Set Reference of the items in source that are missing from diff.

Examples

The following query takes the source Set Reference which is created by locating the search term "fire" in the index named "spells_by_element" and removing all difference Set Reference which was created by locating the search term "water" in the index named "spells_by_element". The Paginate function materialized the results of the Difference operation in a Page.

client.query(
  q.Paginate(
    q.Difference(
      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") ] }
result = client.query(
  q.paginate(
    q.difference(
      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)))]}
result, err := client.Query(
	f.Paginate(
		f.Difference(
			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 0xc000142270 0xc000142270 <nil>}]]
try
{
    Value result = await client.Query(
        Paginate(
            Difference(
                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")))))
Paginate(
  Difference(
    Match(Index('spells_by_element'), 'fire'),
    Match(Index('spells_by_element'), 'water'),
  )
)
{ data: [ Ref(Collection("spells"), "181388642046968320") ] }
Query metrics:

  •    bytesIn:  140

  •   bytesOut:  141

  • computeOps:    1

  •    readOps:    2

  •   writeOps:    0

  •  readBytes:  211

  • writeBytes:    0

  •  queryTime: 11ms

  •    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.Difference(
        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: 1592269416750000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320")
    },
    {
      ts: 1592269416750000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568")
    },
    {
      ts: 1592269416750000,
      action: 'remove',
      document: Ref(Collection("spells"), "181388642071085568")
    }
  ]
}
result = client.query(
  q.paginate(
    q.difference(
      q.match(q.index("spells_by_element"), "fire"),
      q.match(q.index("spells_by_element"), "water")
    ),
    events=True
  )
)
print(result)
{'data': [{'ts': 1592859673180000, 'action': 'add', 'document': Ref(id=181388642046968320, collection=Ref(id=spells, collection=Ref(id=collections)))}, {'ts': 1592859673180000, 'action': 'add', 'document': Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections)))}, {'ts': 1592859673180000, 'action': 'remove', 'document': Ref(id=181388642071085568, collection=Ref(id=spells, collection=Ref(id=collections)))}]}
result, err := client.Query(
	f.Paginate(
		f.Events(
			f.Difference(
				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 0xc0000b1530 0xc0000b1530 <nil>} ts:1603747155400000] map[action:add document:{181388642071085568 0xc0000b1710 0xc0000b1710 <nil>} ts:1603747155400000] map[action:remove document:{181388642071085568 0xc000160090 0xc000160090 <nil>} ts:1603747155400000]]]
try
{
    Value result = await client.Query(
        Paginate(
            Difference(
                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(1603756252570000),action: StringV(add),document: RefV(id = "181388642046968320", collection = RefV(id = "spells", collection = RefV(id = "collections")))), ObjectV(ts: LongV(1603756252570000),action: StringV(add),document: RefV(id = "181388642071085568", collection = RefV(id = "spells", collection = RefV(id = "collections")))), ObjectV(ts: LongV(1603756252570000),action: StringV(remove),document: RefV(id = "181388642071085568", collection = RefV(id = "spells", collection = RefV(id = "collections"))))))
Paginate(
  Events(
    Difference(
      Match(Index('spells_by_element'), 'fire'),
      Match(Index('spells_by_element'), 'water'),
    )
  )
)
{
  data: [
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642046968320")
    },
    {
      ts: 1624310400390000,
      action: 'add',
      document: Ref(Collection("spells"), "181388642071085568")
    },
    {
      ts: 1624310400390000,
      action: 'remove',
      document: Ref(Collection("spells"), "181388642071085568")
    }
  ]
}
Query metrics:

  •    bytesIn:  151

  •   bytesOut:  530

  • computeOps:    1

  •    readOps:    2

  •   writeOps:    0

  •  readBytes:  191

  • writeBytes:    0

  •  queryTime: 10ms

  •    retries:    0

The following query demonstrates how various arrays are compared:

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

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

  •    bytesIn: 136

  •   bytesOut:  29

  • computeOps:   1

  •    readOps:   0

  •   writeOps:   0

  •  readBytes:   0

  • writeBytes:   0

  •  queryTime: 7ms

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