module Fauna::Query

Helpers modeling the FaunaDB Query language.

Helpers are usually used via a concise DSL notation. A DSL block may be used directly with Fauna::Client

client.query { create(class_('spells'), { data: { name: 'Magic Missile' } }) }

To build and return an query expression to execute later, use Fauna::Query.expr

Fauna::Query.expr { create(class_('spells'), { data: { name: 'Magic Missile' } }) }

Or, you may directly use the helper methods:

Fauna::Query.create(Fauna::Query.class_('spells'), { data: { name: 'Magic Missile' } })

Public Class Methods

expr(&block) click to toggle source

Build a query expression.

Allows for unscoped calls to Fauna::Query methods within the provided block. The block should return the constructed query expression.

Example: Fauna::Query.expr { add(1, 2, subtract(3, 2)) }

   # File lib/fauna/query.rb
32 def self.expr(&block)
33   return nil if block.nil?
34 
35   dsl = QueryDSLContext.new
36 
37   Expr.wrap DSLContext.eval_dsl(dsl, &block)
38 end

Authentication Functions

↑ top

Public Instance Methods

has_identity() click to toggle source

A has_identity function

Reference: FaunaDB Authentication

    # File lib/fauna/query.rb
499 def has_identity
500   Expr.new has_identity: nil
501 end
identify(ref, password) click to toggle source

An identify function

Reference: FaunaDB Authentication

    # File lib/fauna/query.rb
483 def identify(ref, password)
484   Expr.new identify: Expr.wrap(ref), password: Expr.wrap(password)
485 end
identity() click to toggle source

An identity function

Reference: FaunaDB Authentication

    # File lib/fauna/query.rb
491 def identity
492   Expr.new identity: nil
493 end
login(ref, params) click to toggle source

A login function

Reference: FaunaDB Authentication

    # File lib/fauna/query.rb
467 def login(ref, params)
468   Expr.new login: Expr.wrap(ref), params: Expr.wrap(params)
469 end
logout(all_tokens) click to toggle source

A logout function

Reference: FaunaDB Authentication

    # File lib/fauna/query.rb
475 def logout(all_tokens)
476   Expr.new logout: Expr.wrap(all_tokens)
477 end

Basic forms

↑ top

Public Instance Methods

at(timestamp, expr) click to toggle source

An at expression

Reference: FaunaDB Basic Forms

   # File lib/fauna/query.rb
89 def at(timestamp, expr)
90   Expr.new at: Expr.wrap(timestamp), expr: Expr.wrap(expr)
91 end
call(name, *args) click to toggle source

A call expression

Reference: FaunaDB Basic Forms

    # File lib/fauna/query.rb
197 def call(name, *args)
198   Expr.new call: Expr.wrap(name), arguments: Expr.wrap_varargs(args)
199 end
do_(*expressions) click to toggle source

A do expression

Reference: FaunaDB Basic Forms

    # File lib/fauna/query.rb
141 def do_(*expressions)
142   Expr.new do: Expr.wrap_varargs(expressions)
143 end
if_(condition, then_, else_) click to toggle source

An if expression

Reference: FaunaDB Basic Forms

    # File lib/fauna/query.rb
133 def if_(condition, then_, else_)
134   Expr.new if: Expr.wrap(condition), then: Expr.wrap(then_), else: Expr.wrap(else_)
135 end
lambda(&block) click to toggle source

A lambda expression

Reference: FaunaDB Basic Forms

This form generates var objects for you, and is called like:

Query.lambda do |a|
  Query.add a, a
end
# Produces: {lambda: :a, expr: {add: [{var: :a}, {var: :a}]}}

Query functions requiring lambdas can be passed blocks without explicitly calling lambda.

You can also use lambda_expr and var directly.

block

Takes one or more var expressions and uses them to construct an expression. If this takes more than one argument, the lambda destructures an array argument. (To destructure single-element arrays use lambda_expr.)

    # File lib/fauna/query.rb
164 def lambda(&block)
165   dsl = Query::QueryDSLContext.new
166   vars =
167     block.parameters.map do |kind, name|
168       fail ArgumentError, 'Splat parameters are not supported in lambda expressions.' if kind == :rest
169       name
170     end
171 
172   case vars.length
173   when 0
174     fail ArgumentError, 'Block must take at least 1 argument.'
175   when 1
176     # When there's only 1 parameter, don't use an array pattern.
177     lambda_expr vars[0], DSLContext.eval_dsl(dsl, var(vars[0]), &block)
178   else
179     lambda_expr vars, DSLContext.eval_dsl(dsl, *(vars.map { |v| var(v) }), &block)
180   end
181 end
lambda_expr(var, expr) click to toggle source

A raw lambda expression

Reference: FaunaDB Basic Forms

See also lambda.

    # File lib/fauna/query.rb
189 def lambda_expr(var, expr)
190   Expr.new lambda: Expr.wrap(var), expr: Expr.wrap(expr)
191 end
let(vars, expr = nil, &block) click to toggle source

A let expression

Only one of expr or block should be provided.

Block example: Fauna.query { let(x: 2) { add(1, x) } }.

Expression example: Fauna.query { let({ x: 2 }, add(1, var(:x))) }.

Reference: FaunaDB Basic Forms

    # File lib/fauna/query.rb
103 def let(vars, expr = nil, &block)
104   in_ =
105     if block.nil?
106       expr
107     else
108       dsl = QueryDSLContext.new
109       dslcls = (class << dsl; self; end)
110 
111       vars.keys.each do |v|
112         dslcls.send(:define_method, v) { var(v) }
113       end
114 
115       DSLContext.eval_dsl(dsl, &block)
116     end
117 
118   Expr.new let: Expr.wrap_values(vars), in: Expr.wrap(in_)
119 end
var(name) click to toggle source

A var expression

Reference: FaunaDB Basic Forms

    # File lib/fauna/query.rb
125 def var(name)
126   Expr.new var: Expr.wrap(name)
127 end

Collection Functions

↑ top

Public Instance Methods

append(collection, elements) click to toggle source

An append expression

Reference: FaunaDB Collections

    # File lib/fauna/query.rb
264 def append(collection, elements)
265   Expr.new append: Expr.wrap(elements), collection: Expr.wrap(collection)
266 end
drop(number, collection) click to toggle source

A drop expression

Reference: FaunaDB Collections

    # File lib/fauna/query.rb
248 def drop(number, collection)
249   Expr.new drop: Expr.wrap(number), collection: Expr.wrap(collection)
250 end
filter(collection, lambda_expr = nil, &lambda_block) click to toggle source

A filter expression

Only one of lambda_expr or lambda_block should be provided. For example: Fauna.query { filter(collection) { |a| equals a, 1 } }.

Reference: FaunaDB Collections

    # File lib/fauna/query.rb
232 def filter(collection, lambda_expr = nil, &lambda_block)
233   Expr.new filter: Expr.wrap(lambda_expr || lambda_block), collection: Expr.wrap(collection)
234 end
foreach(collection, lambda_expr = nil, &lambda_block) click to toggle source

A foreach expression

Only one of lambda_expr or lambda_block should be provided. For example: Fauna.query { foreach(collection) { |a| delete a } }.

Reference: FaunaDB Collections

    # File lib/fauna/query.rb
221 def foreach(collection, lambda_expr = nil, &lambda_block)
222   Expr.new foreach: Expr.wrap(lambda_expr || lambda_block), collection: Expr.wrap(collection)
223 end
map(collection, lambda_expr = nil, &lambda_block) click to toggle source

A map expression

Only one of lambda_expr or lambda_block should be provided. For example: Fauna.query { map(collection) { |a| add a, 1 } }.

Reference: FaunaDB Collections

    # File lib/fauna/query.rb
210 def map(collection, lambda_expr = nil, &lambda_block)
211   Expr.new map: Expr.wrap(lambda_expr || lambda_block), collection: Expr.wrap(collection)
212 end
prepend(collection, elements) click to toggle source

A prepend expression

Reference: FaunaDB Collections

    # File lib/fauna/query.rb
256 def prepend(collection, elements)
257   Expr.new prepend: Expr.wrap(elements), collection: Expr.wrap(collection)
258 end
take(number, collection) click to toggle source

A take expression

Reference: FaunaDB Collections

    # File lib/fauna/query.rb
240 def take(number, collection)
241   Expr.new take: Expr.wrap(number), collection: Expr.wrap(collection)
242 end

Miscellaneous Functions

↑ top

Public Instance Methods

add(*numbers) click to toggle source

An add function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
707 def add(*numbers)
708   Expr.new add: Expr.wrap_varargs(numbers)
709 end
and_(*booleans) click to toggle source

An and function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
779 def and_(*booleans)
780   Expr.new and: Expr.wrap_varargs(booleans)
781 end
class_(name, scope = nil) click to toggle source

A class function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
589 def class_(name, scope = nil)
590   return Expr.new class: Expr.wrap(name) if scope.nil?
591 
592   Expr.new class: Expr.wrap(name), scope: Expr.wrap(scope)
593 end
classes(scope = nil) click to toggle source

A classes function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
627 def classes(scope = nil)
628   Expr.new classes: Expr.wrap(scope)
629 end
contains(path, in_) click to toggle source

A contains function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
683 def contains(path, in_)
684   Expr.new contains: Expr.wrap(path), in: Expr.wrap(in_)
685 end
credentials(scope = nil) click to toggle source

A credentials function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
667 def credentials(scope = nil)
668   Expr.new credentials: Expr.wrap(scope)
669 end
database(name, scope = nil) click to toggle source

A database function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
579 def database(name, scope = nil)
580   return Expr.new database: Expr.wrap(name) if scope.nil?
581 
582   Expr.new database: Expr.wrap(name), scope: Expr.wrap(scope)
583 end
databases(scope = nil) click to toggle source

A databases function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
619 def databases(scope = nil)
620   Expr.new databases: Expr.wrap(scope)
621 end
divide(*numbers) click to toggle source

A divide function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
731 def divide(*numbers)
732   Expr.new divide: Expr.wrap_varargs(numbers)
733 end
equals(*values) click to toggle source

An equals function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
675 def equals(*values)
676   Expr.new equals: Expr.wrap_varargs(values)
677 end
function(name, scope = nil) click to toggle source

A function function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
609 def function(name, scope = nil)
610   return Expr.new function: Expr.wrap(name) if scope.nil?
611 
612   Expr.new function: Expr.wrap(name), scope: Expr.wrap(scope)
613 end
functions(scope = nil) click to toggle source

A functions function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
643 def functions(scope = nil)
644   Expr.new functions: Expr.wrap(scope)
645 end
gt(*values) click to toggle source

A greater than function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
763 def gt(*values)
764   Expr.new gt: Expr.wrap_varargs(values)
765 end
gte(*values) click to toggle source

A greater than or equal function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
771 def gte(*values)
772   Expr.new gte: Expr.wrap_varargs(values)
773 end
index(name, scope = nil) click to toggle source

An index function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
599 def index(name, scope = nil)
600   return Expr.new index: Expr.wrap(name) if scope.nil?
601 
602   Expr.new index: Expr.wrap(name), scope: Expr.wrap(scope)
603 end
indexes(scope = nil) click to toggle source

An indexes function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
635 def indexes(scope = nil)
636   Expr.new indexes: Expr.wrap(scope)
637 end
keys(scope = nil) click to toggle source

A keys function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
659 def keys(scope = nil)
660   Expr.new keys: Expr.wrap(scope)
661 end
lt(*values) click to toggle source

A less than function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
747 def lt(*values)
748   Expr.new lt: Expr.wrap_varargs(values)
749 end
lte(*values) click to toggle source

A less than or equal function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
755 def lte(*values)
756   Expr.new lte: Expr.wrap_varargs(values)
757 end
modulo(*numbers) click to toggle source

A modulo function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
739 def modulo(*numbers)
740   Expr.new modulo: Expr.wrap_varargs(numbers)
741 end
multiply(*numbers) click to toggle source

A multiply function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
715 def multiply(*numbers)
716   Expr.new multiply: Expr.wrap_varargs(numbers)
717 end
new_id() click to toggle source

A new_id function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
571 def new_id
572   Expr.new new_id: nil
573 end
next_id() click to toggle source

A next_id function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
561 def next_id
562   Expr.new next_id: nil
563 end
not_(boolean) click to toggle source

A not function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
795 def not_(boolean)
796   Expr.new not: Expr.wrap(boolean)
797 end
or_(*booleans) click to toggle source

An or function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
787 def or_(*booleans)
788   Expr.new or: Expr.wrap_varargs(booleans)
789 end
select(path, from, params = {}) click to toggle source

A select function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
691 def select(path, from, params = {})
692   Expr.new Expr.wrap_values(params).merge(select: Expr.wrap(path), from: Expr.wrap(from))
693 end
select_all(path, from) click to toggle source

A select_all function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
699 def select_all(path, from)
700   Expr.new select_all: Expr.wrap(path), from: Expr.wrap(from)
701 end
subtract(*numbers) click to toggle source

A subtract function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
723 def subtract(*numbers)
724   Expr.new subtract: Expr.wrap_varargs(numbers)
725 end
tokens(scope = nil) click to toggle source

A tokens function

Reference: FaunaDB Miscellaneous Functions

    # File lib/fauna/query.rb
651 def tokens(scope = nil)
652   Expr.new tokens: Expr.wrap(scope)
653 end

Read Functions

↑ top

Public Instance Methods

exists(ref, params = {}) click to toggle source

An exists expression

Reference: FaunaDB Read functions

    # File lib/fauna/query.rb
298 def exists(ref, params = {})
299   Expr.new Expr.wrap_values(params).merge(exists: Expr.wrap(ref))
300 end
get(ref, params = {}) click to toggle source

A get expression

Reference: FaunaDB Read functions

    # File lib/fauna/query.rb
274 def get(ref, params = {})
275   Expr.new Expr.wrap_values(params).merge(get: Expr.wrap(ref))
276 end
key_from_secret(secret) click to toggle source

A key_from_secret expression

Reference: FaunaDB Read functions

    # File lib/fauna/query.rb
282 def key_from_secret(secret)
283   Expr.new key_from_secret: Expr.wrap(secret)
284 end
paginate(set, params = {}) click to toggle source

A paginate expression

Reference: FaunaDB Read functions

    # File lib/fauna/query.rb
290 def paginate(set, params = {})
291   Expr.new Expr.wrap_values(params).merge(paginate: Expr.wrap(set))
292 end

Set Functions

↑ top

Public Instance Methods

difference(*sets) click to toggle source

A difference expression

Reference: FaunaDB Sets

    # File lib/fauna/query.rb
438 def difference(*sets)
439   Expr.new difference: Expr.wrap_varargs(sets)
440 end
distinct(set) click to toggle source

A distinct expression

Reference: FaunaDB Sets

    # File lib/fauna/query.rb
446 def distinct(set)
447   Expr.new distinct: Expr.wrap(set)
448 end
events(ref_set) click to toggle source

An events expression

Reference: FaunaDB Sets

    # File lib/fauna/query.rb
406 def events(ref_set)
407   Expr.new events: Expr.wrap(ref_set)
408 end
intersection(*sets) click to toggle source

An intersection expression

Reference: FaunaDB Sets

    # File lib/fauna/query.rb
430 def intersection(*sets)
431   Expr.new intersection: Expr.wrap_varargs(sets)
432 end
join(source, target_expr = nil, &target_block) click to toggle source

A join expression

Only one of target_expr or target_block should be provided. For example: Fauna.query { join(source) { |x| match some_index, x } }.

Reference: FaunaDB Sets

    # File lib/fauna/query.rb
457 def join(source, target_expr = nil, &target_block)
458   Expr.new join: Expr.wrap(source), with: Expr.wrap(target_expr || target_block)
459 end
match(index, *terms) click to toggle source

A match expression

Reference: FaunaDB Sets

    # File lib/fauna/query.rb
414 def match(index, *terms)
415   Expr.new match: Expr.wrap(index), terms: Expr.wrap_varargs(terms)
416 end
singleton(ref) click to toggle source

A singleton expression

Reference: FaunaDB Sets

    # File lib/fauna/query.rb
398 def singleton(ref)
399   Expr.new singleton: Expr.wrap(ref)
400 end
union(*sets) click to toggle source

A union expression

Reference: FaunaDB Sets

    # File lib/fauna/query.rb
422 def union(*sets)
423   Expr.new union: Expr.wrap_varargs(sets)
424 end

String Functions

↑ top

Public Instance Methods

casefold(string, normalizer = nil) click to toggle source

A casefold function

Reference: FaunaDB String Functions

    # File lib/fauna/query.rb
521 def casefold(string, normalizer = nil)
522   if normalizer.nil?
523     Expr.new casefold: Expr.wrap(string)
524   else
525     Expr.new casefold: Expr.wrap(string), normalizer: Expr.wrap(normalizer)
526   end
527 end
concat(strings, separator = nil) click to toggle source

A concat function

Reference: FaunaDB String Functions

    # File lib/fauna/query.rb
509 def concat(strings, separator = nil)
510   if separator.nil?
511     Expr.new concat: Expr.wrap(strings)
512   else
513     Expr.new concat: Expr.wrap(strings), separator: Expr.wrap(separator)
514   end
515 end

Time and Date Functions

↑ top

Public Instance Methods

date(string) click to toggle source

A date expression

Reference: FaunaDB Time Functions

    # File lib/fauna/query.rb
551 def date(string)
552   Expr.new date: Expr.wrap(string)
553 end
epoch(number, unit) click to toggle source

An epoch expression

Reference: FaunaDB Time Functions

    # File lib/fauna/query.rb
543 def epoch(number, unit)
544   Expr.new epoch: Expr.wrap(number), unit: Expr.wrap(unit)
545 end
time(string) click to toggle source

A time expression

Reference: FaunaDB Time Functions

    # File lib/fauna/query.rb
535 def time(string)
536   Expr.new time: Expr.wrap(string)
537 end

Values

↑ top

Public Instance Methods

abort(msg) click to toggle source

An abort expression

Reference: FaunaDB Basic Forms

   # File lib/fauna/query.rb
58 def abort(msg)
59   Expr.new abort: Expr.wrap(msg)
60 end
object(fields) click to toggle source

An object expression

Query expression constructs can also take a regular ruby object, so the following are equivalent:

Fauna.query { { x: 1, y: add(1, 2) } }
Fauna.query { object(x: 1, y: add(1, 2)) }

Reference: FaunaDB Basic Forms

   # File lib/fauna/query.rb
71 def object(fields)
72   Expr.new object: Expr.wrap_values(fields)
73 end
query(expr) click to toggle source

A query expression

Reference: FaunaDB Basic Forms

   # File lib/fauna/query.rb
79 def query(expr)
80   Expr.new query: Expr.wrap(expr)
81 end
ref(str, id = nil) click to toggle source

Construct a ref value

Reference: FaunaDB Values

   # File lib/fauna/query.rb
46 def ref(str, id = nil)
47   if id.nil?
48     Expr.new :@ref => Expr.wrap(str)
49   else
50     Expr.new ref: Expr.wrap(str), id: Expr.wrap(id)
51   end
52 end

Write Functions

↑ top

Public Instance Methods

create(class_ref, params) click to toggle source

A create expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
308 def create(class_ref, params)
309   Expr.new create: Expr.wrap(class_ref), params: Expr.wrap(params)
310 end
create_class(params) click to toggle source

A create class expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
356 def create_class(params)
357   Expr.new create_class: Expr.wrap(params)
358 end
create_database(params) click to toggle source

A create database expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
372 def create_database(params)
373   Expr.new create_database: Expr.wrap(params)
374 end
create_function(params) click to toggle source

A create function expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
388 def create_function(params)
389   Expr.new create_function: Expr.wrap(params)
390 end
create_index(params) click to toggle source

A create index expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
364 def create_index(params)
365   Expr.new create_index: Expr.wrap(params)
366 end
create_key(params) click to toggle source

A create key expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
380 def create_key(params)
381   Expr.new create_key: Expr.wrap(params)
382 end
delete(ref) click to toggle source

A delete expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
332 def delete(ref)
333   Expr.new delete: Expr.wrap(ref)
334 end
insert(ref, ts, action, params) click to toggle source

An insert expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
340 def insert(ref, ts, action, params)
341   Expr.new insert: Expr.wrap(ref), ts: Expr.wrap(ts), action: Expr.wrap(action), params: Expr.wrap(params)
342 end
remove(ref, ts, action) click to toggle source

A remove expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
348 def remove(ref, ts, action)
349   Expr.new remove: Expr.wrap(ref), ts: Expr.wrap(ts), action: Expr.wrap(action)
350 end
replace(ref, params) click to toggle source

A replace expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
324 def replace(ref, params)
325   Expr.new replace: Expr.wrap(ref), params: Expr.wrap(params)
326 end
update(ref, params) click to toggle source

An update expression

Reference: FaunaDB Write functions

    # File lib/fauna/query.rb
316 def update(ref, params)
317   Expr.new update: Expr.wrap(ref), params: Expr.wrap(params)
318 end