Struct Query 

pub struct Query<'a> { /* private fields */ }

This represents a query that can be performed on an AnnotationStore via AnnotationStore::query() to obtain anything in the store. A query can be formulated in STAMQL, a dedicated query language (via Query::parse(), or it can be instantiated programmatically via Query::new().

A query consists of a query type (QueryType), a result type (subset of Type), a variable to bind to (optional), and zero or more constraints (Constraint), and optionally a subquery.

Examples

select all occurrences of the text “fly”

let query = Query::parse("SELECT TEXT WHERE
                                 TEXT \"fly\";")?;

the same query as above but constructed directly instead of via STAMQL, this is always more performant as it bypasses the parsing stage. It does not affect the runtime performance of the query evaluation itself though:

let query = Query::new(QueryType::Select, Some(Type::TextSelection), None)
                  .with_constraint(Constraint::Text("fly", TextMode::Exact));

select all annotations that targets the text “fly”

let query = Query::parse("SELECT ANNOTATION WHERE
                                 TEXT \"fly\";")?;

select all annotations with data ‘part-of-speech’ and value ‘noun’ (ad-hoc vocab!), bind the result to a variable

let query = Query::parse("SELECT ANNOTATION ?noun WHERE
                                 DATA \"myset\" \"part-of-speech\" = \"noun\";")?;

the same query as above but constructed programmatically:

let query = Query::new(QueryType::Select, Some(Type::Annotation), Some("noun"))
                  .with_constraint(Constraint::KeyValue {
                           set: "myset",
                           key: "fly",
                           operator: DataOperator::Equals("noun".into()),
                           qualifier: SelectionQualifier::Normal
                  });

select all annotations that have a part-of-speech annotation (regardless of the value)

let query = Query::parse("SELECT ANNOTATION ?pos WHERE
                                 DATA \"myset\" \"part-of-speech\";")?;

select all annotations with data ‘part-of-speech’ made by a certain annotator (ad-hoc vocab!)

let query = Query::parse("SELECT ANNOTATION WHERE
                             DATA \"myset\" \"part-of-speech\" = \"noun\";
                             DATA \"myset\" \"annotator\" = \"John Doe\";")?;

select sentences with a particular annotated text in it, as formulated via a subquery

let query = Query::parse("SELECT TEXT ?sentence WHERE
                                 DATA \"myset\" \"type\" = \"sentence\";
                                   {
                                    SELECT TEXT ?fly WHERE
                                        RELATION ?sentence EMBEDS;
                                        DATA \"myset\" \"part-of-speech\" = \"noun\";
                                        TEXT \"fly\";
                                   }")?;

Implementations

impl<'a> Query<'a>

pub fn new( querytype: QueryType, resulttype: Option<Type>, name: Option<&'a str>, ) -> Self

Instantiate a new query. See the top-level documentation of Query for examples.

pub fn select_by_path(&self, querypath: QueryPathRef<'_>) -> Option<&Query<'a>>

Selects this query or a specific subquery anywhere in its tree based on a given query path. A querypath is a list of indices selecting subqueries, e.g. [0,0,1] for main query, first subquery, then second subquery). The first item (main query) is always 0 Return None when the path does not resolve.

pub fn with_qualifier(self, qualifier: QueryQualifier) -> Self

Set a qualifier for the query

pub fn with_constraint(self, constraint: Constraint<'a>) -> Self

Add a constraint to the query

pub fn constrain(&mut self, constraint: Constraint<'a>) -> &mut Self

Add a constraint to the query

pub fn with_subquery(self, query: Query<'a>) -> Self

Set the subquery for this query

pub fn with_name(self, name: &'a str) -> Self

pub fn has_subqueries(&self) -> bool

Does this query have subqueries?

pub fn subqueries_len(&self) -> usize

Returns the number of subqueries

pub fn subqueries(&self) -> impl Iterator<Item = &Query<'a>>

Returns an iterator over the direct subqueries (i.e. non-recursively) Use queries() for recursion.

pub fn qualifier(&self) -> QueryQualifier

Return the qualifier for the query

pub fn querypaths(&self) -> Vec<QueryPath>

Return all querypaths (relative to the current query as root!), including the one referencing self This should only be run on a root query

pub fn queries(&self) -> impl Iterator<Item = (QueryPath, &Query<'a>)>

Returns an iterator over self and all subqueries (i.e. recursively) Note: this always returns self as first element

pub fn names(&self) -> Vec<&'a str>

Returns all variable names occur that occur in this query, including in all possible subqueries.

pub fn constraints<'s>(&'s self) -> Iter<'s, Constraint<'a>>

Iterates over all constraints in the Query

pub fn attributes<'s>(&'s self) -> Iter<'s, &'a str>

Returns all attributes for this query

pub fn constraints_with_attributes( &self, ) -> impl Iterator<Item = (&Constraint<'a>, &Vec<&'a str>)>

Iterates over all constraints and their attributes in the Query

pub fn iter<'s>(&'s self) -> Iter<'s, Constraint<'a>>

Iterates over all constraints in the Query Alias for constraints(),

pub fn assignments<'s>(&'s self) -> Iter<'s, Assignment<'a>>

Iterates over all assignments in the Query

pub fn name(&self) -> Option<&'a str>

Returns the variable name of the Query, the ? prefix STAMQL uses is never included.

pub fn querytype(&self) -> QueryType

Returns the type of the query

pub fn resulttype(&self) -> Option<Type>

Returns the type of the results that this query produces

pub fn resulttype_as_str(&self) -> Option<&'static str>

Returns the type of the results that this query produces, as a STAMQL keyword.

pub fn parse(querystring: &'a str) -> Result<(Self, &'a str), StamError>

Parses a query formulated in STAMQL. Returns the Query if successful, it can subsequently by passed to [AnnotationStore.query()] or a StamError::QuerySyntaxError if the query is not valid. See the documentation on Query itself for examples.

pub fn with_annotationvar( self, name: impl Into<String>, annotation: &ResultItem<'_, Annotation>, ) -> Self

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn bind_annotationvar( &mut self, name: impl Into<String>, annotation: &ResultItem<'_, Annotation>, )

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn with_datavar( self, name: impl Into<String>, data: &ResultItem<'_, AnnotationData>, ) -> Self

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn bind_datavar( &mut self, name: impl Into<String>, data: &ResultItem<'_, AnnotationData>, )

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn with_keyvar( self, name: impl Into<String>, key: &ResultItem<'_, DataKey>, ) -> Self

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn bind_keyvar( &mut self, name: impl Into<String>, key: &ResultItem<'_, DataKey>, )

Bind a variable, the name should not include the ? prefix STAMQL uses.

pub fn with_substorevar( self, name: impl Into<String>, substore: &ResultItem<'_, AnnotationSubStore>, ) -> Self

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn bind_substorevar( &mut self, name: impl Into<String>, substore: &ResultItem<'_, AnnotationSubStore>, )

Bind a variable, the name should not include the ? prefix STAMQL uses.

pub fn with_textvar( self, name: impl Into<String>, textselection: &ResultTextSelection<'_>, ) -> Self

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn bind_textvar( &mut self, name: impl Into<String>, textselection: &ResultTextSelection<'_>, )

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn with_resourcevar( self, name: impl Into<String>, resource: &ResultItem<'_, TextResource>, ) -> Self

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn bind_resourcevar( &mut self, name: impl Into<String>, resource: &ResultItem<'_, TextResource>, )

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn with_datasetvar( self, name: impl Into<String>, dataset: &ResultItem<'_, AnnotationDataSet>, ) -> Self

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn bind_datasetvar( &mut self, name: impl Into<String>, dataset: &ResultItem<'_, AnnotationDataSet>, )

Bind a variable, the name should not include the ? prefix STAMQL uses. This is a context variable that will be available to the query, but will not be propagated to the results.

pub fn bind_from_result( &mut self, varname: impl Into<String>, resultitem: &QueryResultItem<'_>, )

Bind any variable from a QueryResultItem as a context variable in this query

pub fn to_string(&self) -> Result<String, StamError>

Serialize the query to a STAMQL String

Trait Implementations

impl<'a> Clone for Query<'a>

fn clone(&self) -> Query<'a>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<'a> Debug for Query<'a>

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

Formats the value using the given formatter.

impl<'a> TryFrom<&'a str> for Query<'a>

type Error = StamError

The type returned in the event of a conversion error.

fn try_from(querystring: &'a str) -> Result<Self, Self::Error>

Performs the conversion.