Struct aragog::query::Query

pub struct Query {
    pub bind_vars: HashMap<String, Value>,
    /* private fields */
}

A query utility for ArangoDB to avoid writing simple AQL strings. After building can be rendered as an AQL string with the aql_str method.

Examples

#[derive(Clone, Serialize, Deserialize, Record)]
pub struct User {
    pub username: String
}

// You can init a query in three ways, the following lines do the exact same thing
let query = Query::new("Users");
let query2 = User::query(); // `User` needs to implement `Record`
let query3 = query!("Users");

Fields

bind_vars: HashMap<String, Value>

bind parameters to substitute in query string

Implementations

impl Query

pub fn new(collection_name: &str) -> Self

Creates a new empty Query. You can call filter, sort, limit and distinct to customize the query afterwards

Arguments

• collection_name- The name of the queried collection

Example

let query = Query::new("User");

pub fn bind_var(self, var: &str, value: impl Into<Value>) -> Self

Binds var attribute to be substituted by value in the query string

pub fn try_bind_var( self, var: &str, value: impl Serialize ) -> Result<Self, Error>

Tries to bind var attribute to be substituted by value in the query string

Errors

Returns an error if value can’t be converted to a serde_json::Value

pub fn outbound(min: u16, max: u16, edge_collection: &str, vertex: &str) -> Self

Creates a new outbound traversing Query though a edge_collection. You can call filter, sort, limit and distinct to customize the query afterwards

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• edge_collection- The name of the traversed edge collection
• vertex - The _id of the starting document (User/123 for example)

Example

let query = Query::outbound(1, 2, "ChildOf", "User/123");

pub fn outbound_graph( min: u16, max: u16, named_graph: &str, vertex: &str ) -> Self

Creates a new outbound traversing Query though a named_grah. You can call filter, sort, limit and distinct to customize the query afterwards

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• named_graph- The named graph to traverse
• vertex - The _id of the starting document (User/123 for example)

Example

let query = Query::outbound_graph(1, 2, "SomeGraph", "User/123");

pub fn any(min: u16, max: u16, edge_collection: &str, vertex: &str) -> Self

Creates a new ANY traversing Query though a edge_collection. You can call filter, sort, limit and distinct to customize the query afterwards

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• edge_collection- The name of the traversed edge collection
• vertex - The _id of the starting document (User/123 for example)

Example

let query = Query::outbound(1, 2, "ChildOf", "User/123");

pub fn any_graph(min: u16, max: u16, named_graph: &str, vertex: &str) -> Self

Creates a new ANY traversing Query though a named_grah. You can call filter, sort, limit and distinct to customize the query afterwards

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• named_graph- The named graph to traverse
• vertex - The _id of the starting document (User/123 for example)

Example

let query = Query::outbound_graph(1, 2, "SomeGraph", "User/123");

pub fn inbound(min: u16, max: u16, edge_collection: &str, vertex: &str) -> Self

Creates a new inbound traversing Query though a edge_collection. You can call filter, sort, limit and distinct to customize the query afterwards

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• edge_collection- The name of the traversed edge collection
• vertex - The _id of the starting document (User/123 for example)

Example

let query = Query::inbound(1, 2, "ChildOf", "User/123");

pub fn inbound_graph( min: u16, max: u16, named_graph: &str, vertex: &str ) -> Self

Creates a new inbound traversing Query though a named_grah. You can call filter, sort, limit and distinct to customize the query afterwards

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• named_graph- The named graph to traverse
• vertex - The _id of the starting document (User/123 for example)

Example

let query = Query::inbound_graph(1, 2, "SomeGraph", "User/123");

pub fn join_outbound( self, min: u16, max: u16, named_graph: bool, query: Self ) -> Self

Adds an outbound traversing query to the current Query.

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• named_graph - Is the following query on a Named graph?
• query - The sub query to add

Example

let query = Query::new("User").join_outbound(1, 2, false, Query::new("ChildOf"));
assert_eq!(query.aql_str(), String::from("\
    FOR b in User \
        FOR a in 1..2 OUTBOUND b ChildOf \
        return a\
"));
let query = Query::new("User").join_outbound(1, 2, true, Query::new("NamedGraph"));
assert_eq!(query.aql_str(), String::from("\
    FOR b in User \
        FOR a in 1..2 OUTBOUND b GRAPH NamedGraph \
        return a\
"));

pub fn join_inbound( self, min: u16, max: u16, named_graph: bool, query: Self ) -> Self

Adds an inbound traversing query to the current Query.

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• named_graph - Is the following query on a Named graph?
• query - The sub query to add

Example

let query = Query::new("User").join_inbound(1, 2, false, Query::new("ChildOf"));
assert_eq!(query.aql_str(), String::from("\
    FOR b in User \
        FOR a in 1..2 INBOUND b ChildOf \
        return a\
"));
let query = Query::new("User").join_inbound(1, 2, true, Query::new("NamedGraph"));
assert_eq!(query.aql_str(), String::from("\
    FOR b in User \
        FOR a in 1..2 INBOUND b GRAPH NamedGraph \
        return a\
"));

pub fn join_any( self, min: u16, max: u16, named_graph: bool, query: Self ) -> Self

Adds an ANY traversing query to the current Query.

Arguments

• min - The minimum depth of the graph request
• max - The maximum depth of the graph request
• named_graph - Is the following query on a Named graph?
• query - The sub query to add

Example

let query = Query::new("User").join_any(1, 2, false, Query::new("ChildOf"));
assert_eq!(query.aql_str(), String::from("\
    FOR b in User \
        FOR a in 1..2 ANY b ChildOf \
        return a\
"));
let query = Query::new("User").join_any(1, 2, true, Query::new("NamedGraph"));
assert_eq!(query.aql_str(), String::from("\
    FOR b in User \
        FOR a in 1..2 ANY b GRAPH NamedGraph \
        return a\
"));

pub fn with_collections(self, collections: &[&str]) -> Self

Allow the current traversing Query to filter the traversed collections and avoid potentian deadlocks.

Arguments

• collections - The names of the collections the query can traverse

Example

let query = Query::new("User").with_collections(&["User", "Client"]).join_any(1, 2, false, Query::new("ChildOf"));
assert_eq!(query.aql_str(), String::from("\
    WITH User, Client \
    FOR b in User \
        FOR a in 1..2 ANY b ChildOf \
        return a\
"));

pub fn sort(self, field: &str, direction: Option<SortDirection>) -> Self

Allows to sort a current Query by different field names. The fields must exist or the query won’t work. Every time the method is called, a new sorting condition is added.

Note

If you add mutliple sort calls it will result in something like SORT a.field, b.field, c.field. If you separate the calls by a limit or other operation, the order will be respected and the resulting query will look like SORT a.field LIMIT 10 SORT b.field, c.field

Arguments

• field: The field name, must exist in the collection
• direction: Optional sorting direction for that field. The direction is optional because ArangoDB uses ASC sorting by default

Example

let query = Query::new("User")
    .sort("username", Some(SortDirection::Desc))
    .sort("age", Some(SortDirection::Asc)
);

pub fn filter(self, filter: Filter) -> Self

Allows to filter a current Query by different comparisons.

Example

let query = Query::new("User").filter(Filter::new(Comparison::field("age").greater_than(18)));
// or
let query = Query::new("User").filter(Comparison::field("age").greater_than(18).into());

pub fn prune(self, filter: Filter) -> Self

Allows to filter a current Query by different comparisons but using the PRUNE keyword.

Note

The prune operation only works for graph queries (See ArangoDB documentation)

Example

let query = Query::outbound(1, 2, "ChildOf", "User/123").prune(Filter::new(Comparison::field("age").greater_than(18)));
// or
let query = Query::outbound(1, 2, "ChildOf", "User/123").prune(Comparison::field("age").greater_than(18).into());

pub fn limit(self, limit: u32, skip: Option<u32>) -> Self

Allows to paginate a current Query.

Arguments

• limit - the maximum returned elements
• skip- optional number of skipped elements

Example

// We want maximum 10 elements but skip the first 5
let query = Query::new("User").limit(10, Some(5));

pub const fn distinct(self) -> Self

Allows to avoid duplicate elements for a Query.

Note

If you use sub-queries, only the distinct on the last sub query will be used.

Example

let query = Query::new("User")
    .filter(Filter::new(Comparison::field("age").greater_than(18)))
    .distinct();

pub fn to_aql(&self) -> String

👎Deprecated since 0.17.0: use aql_str instead

Renders the AQL string corresponding to the current Query

Example

let mut query = Query::new("User").filter(Filter::new(Comparison::field("age").greater_than(10)).
    or(Comparison::field("username").in_str_array(&["Felix", "Bianca"]))).distinct();
assert_eq!(query.to_aql(), String::from("\
    FOR a in User \
        FILTER a.age > 10 || a.username IN [\"Felix\", \"Bianca\"] \
        return DISTINCT a\
"));

pub fn aql_str(&self) -> String

Renders the AQL string corresponding to the current Query

Example

let mut query = Query::new("User").filter(Filter::new(Comparison::field("age").greater_than(10)).
    or(Comparison::field("username").in_str_array(&["Felix", "Bianca"]))).distinct();
assert_eq!(query.aql_str(), String::from("\
    FOR a in User \
        FILTER a.age > 10 || a.username IN [\"Felix\", \"Bianca\"] \
        return DISTINCT a\
"));

pub async fn raw_call<D>( &self, db_accessor: &D ) -> Result<QueryResult<UndefinedRecord>, Error>where D: DatabaseAccess + ?Sized,

Finds all documents in database matching the current Query. This will return a wrapper for serde_json::Value as an UndefinedRecord

Note

Simple wrapper for DatabaseAccess::query. Useful for queries returning various collection records.

pub async fn call<D, T>(&self, db_accessor: &D) -> Result<QueryResult<T>, Error>where D: DatabaseAccess + ?Sized, T: Record + Send,

Finds all records in database matching the current Query.

Note

Simple wrapper for Record::get

pub async fn raw_call_in_batches<D>( &self, db_accessor: &D, batch_size: u32 ) -> Result<QueryCursor<UndefinedRecord>, Error>where D: DatabaseAccess + ?Sized,

Finds all documents in database matching the current Query using batches. This will return a wrapper for serde_json::Value as an UndefinedRecord inside a cursor.

Note

Simple wrapper for DatabaseAccess::query_in_batches. Useful for queries returning various collection records.

pub async fn call_in_batches<D, T>( &self, db_accessor: &D, batch_size: u32 ) -> Result<QueryCursor<T>, Error>where D: DatabaseAccess + ?Sized, T: Record + Send,

Finds all records in database matching the current Query using batches.

Note

Simple wrapper for Record::get_in_batches

Trait Implementations

impl Clone for Query

fn clone(&self) -> Query

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Query

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Query

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.