Struct stam::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"),
                           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 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 subquery(&self) -> Option<&Query<'a>>

REturns the subquery (if any)

pub fn last_subquery(&self) -> &Query<'a>

Returns the last subquery (if any), otherwise returns this query itself

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

Iterates over all constraints 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<'a, 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<'a, 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<'a, 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<'a, 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<'a, 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<'a, DataKey> )

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

pub fn with_textvar( self, name: impl Into<String>, textselection: ResultTextSelection<'a> ) -> 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<'a> )

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<'a, 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<'a, 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<'a, 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<'a, 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 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 copy 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.