## Query

Query — Query object API, parsing and execution

## Synopsis

    enum                rasqal_query_verb;
    typedef             rasqal_query;
    rasqal_query*       rasqal_new_query                    (rasqal_world *world,
                                                             const char *name,
                                                             unsigned char *uri);
    void                rasqal_free_query                   (rasqal_query *query);
    int                 rasqal_query_add_data_graph         (rasqal_query *query,
                                                             raptor_uri *uri,
                                                             raptor_uri *name_uri,
                                                             int flags);
    int                 rasqal_query_add_prefix             (rasqal_query *query,
                                                             rasqal_prefix *prefix);
    int                 rasqal_query_add_variable           (rasqal_query *query,
                                                             rasqal_variable *var);
    rasqal_query_results* rasqal_query_execute              (rasqal_query *query);
    raptor_sequence*    rasqal_query_get_all_variable_sequence
                                                            (rasqal_query *query);
    raptor_sequence*    rasqal_query_get_anonymous_variable_sequence
                                                            (rasqal_query *query);
    raptor_sequence*    rasqal_query_get_bound_variable_sequence
                                                            (rasqal_query *query);
    rasqal_triple*      rasqal_query_get_construct_triple   (rasqal_query *query,
                                                             int idx);
    raptor_sequence*    rasqal_query_get_construct_triples_sequence
                                                            (rasqal_query *query);
    rasqal_data_graph*  rasqal_query_get_data_graph         (rasqal_query *query,
                                                             int idx);
    raptor_sequence*    rasqal_query_get_data_graph_sequence
                                                            (rasqal_query *query);
    int                 rasqal_query_get_distinct           (rasqal_query *query);
    int                 rasqal_query_get_explain            (rasqal_query *query);
    rasqal_expression*  rasqal_query_get_group_condition    (rasqal_query *query,
                                                             int idx);
    raptor_sequence*    rasqal_query_get_group_conditions_sequence
                                                            (rasqal_query *query);
    rasqal_graph_pattern* rasqal_query_get_graph_pattern    (rasqal_query *query,
                                                             int idx);
    raptor_sequence*    rasqal_query_get_graph_pattern_sequence
                                                            (rasqal_query *query);
    const char*         rasqal_query_get_label              (rasqal_query *query);
    int                 rasqal_query_get_limit              (rasqal_query *query);
    const char*         rasqal_query_get_name               (rasqal_query *query);
    int                 rasqal_query_get_offset             (rasqal_query *query);
    rasqal_expression*  rasqal_query_get_order_condition    (rasqal_query *query,
                                                             int idx);
    raptor_sequence*    rasqal_query_get_order_conditions_sequence
                                                            (rasqal_query *query);
    rasqal_prefix*      rasqal_query_get_prefix             (rasqal_query *query,
                                                             int idx);
    raptor_sequence*    rasqal_query_get_prefix_sequence    (rasqal_query *query);
    rasqal_graph_pattern* rasqal_query_get_query_graph_pattern
                                                            (rasqal_query *query);
    rasqal_triple*      rasqal_query_get_triple             (rasqal_query *query,
                                                             int idx);
    raptor_sequence*    rasqal_query_get_triple_sequence    (rasqal_query *query);
    void*               rasqal_query_get_user_data          (rasqal_query *query);
    rasqal_variable*    rasqal_query_get_variable           (rasqal_query *query,
                                                             int idx);
    rasqal_query_verb   rasqal_query_get_verb               (rasqal_query *query);
    int                 rasqal_query_get_wildcard           (rasqal_query *query);
    int                 rasqal_query_has_variable           (rasqal_query *query,
                                                             unsigned char *name);
    int                 rasqal_query_prepare                (rasqal_query *query,
                                                             unsigned char *query_string,
                                                             raptor_uri *base_uri);
    void                rasqal_query_print                  (rasqal_query *query,
                                                             FILE *fh);
    void                rasqal_query_graph_pattern_visit    (rasqal_query *query,
                                                             rasqal_graph_pattern_visit_fn visit_fn,
                                                             void *data);
    void                rasqal_query_set_default_generate_bnodeid_parameters
                                                            (rasqal_query *rdf_query,
                                                             char *prefix,
                                                             int base);
    void                rasqal_query_set_distinct           (rasqal_query *query,
                                                             int distinct_mode);
    void                rasqal_query_set_explain            (rasqal_query *query,
                                                             int is_explain);
    void                rasqal_query_set_error_handler      (rasqal_query *query,
                                                             void *user_data,
                                                             raptor_message_handler handler);
    void                rasqal_query_set_fatal_error_handler
                                                            (rasqal_query *query,
                                                             void *user_data,
                                                             raptor_message_handler handler);
    void                rasqal_query_set_generate_bnodeid_handler
                                                            (rasqal_query *query,
                                                             void *user_data,
                                                             rasqal_generate_bnodeid_handler handler);
    void                rasqal_query_set_limit              (rasqal_query *query,
                                                             int limit);
    void                rasqal_query_set_offset             (rasqal_query *query,
                                                             int offset);
    void                rasqal_query_set_user_data          (rasqal_query *query,
                                                             void *user_data);
    int                 rasqal_query_set_variable           (rasqal_query *query,
                                                             unsigned char *name,
                                                             rasqal_literal *value);
    void                rasqal_query_set_warning_handler    (rasqal_query *query,
                                                             void *user_data,
                                                             raptor_message_handler handler);
    const char*         rasqal_query_verb_as_string         (rasqal_query_verb verb);
    int                 rasqal_query_write                  (raptor_iostream *iostr,
                                                             rasqal_query *query,
                                                             raptor_uri *format_uri,
                                                             raptor_uri *base_uri);
    int                 rasqal_query_iostream_write_escaped_counted_string
                                                            (rasqal_query *query,
                                                             raptor_iostream *iostr,
                                                             unsigned char *string,
                                                             size_t len);
    unsigned char*      rasqal_query_escape_counted_string  (rasqal_query *query,
                                                             unsigned char *string,
                                                             size_t len,
                                                             size_t *output_len_p);
    int                 rasqal_query_set_feature            (rasqal_query *query,
                                                             rasqal_feature feature,
                                                             int value);
    int                 rasqal_query_set_feature_string     (rasqal_query *query,
                                                             rasqal_feature feature,
                                                             unsigned char *value);
    int                 rasqal_query_get_feature            (rasqal_query *query,
                                                             rasqal_feature feature);
    const unsigned char* rasqal_query_get_feature_string    (rasqal_query *query,
                                                             rasqal_feature feature);

## Description

This class provides the main interface to the library. A query can be constructed by parsing a string, retrieving it from a URI and/or constructing it via API methods to build the query expression.

The query structures can be read via methods to return the query verb `rasqal_query_get_verb()`, the rasqal_data_graph RDF data sources with `rasqal_query_get_data_graph()` etc., the rasqal_graph_pattern tree with `rasqal_query_get_query_graph_pattern()`, the sequence of order conditions with `rasqal_query_get_order_condition()` etc., the rasqal_variable selected to return with `rasqal_query_get_bound_variable_sequence()` or `rasqal_query_get_all_variable_sequence()`, and so on.

To process a query string, the `rasqal_query_prepare()` method parses the query string in some query language and initialises the rasqal_query structures.

The query can be evaluated with the internal query engine against some source of matches using `rasqal_query_execute()` to give an rasqal_query_results. There are multiple forms of results that can include variable bindings, a boolean or an RDF graph that can be tested for with methods on rasqal_query_results and then retrieved.

## Details

### enum rasqal_query_verb

    typedef enum {
      /* internal */
      RASQAL_QUERY_VERB_UNKNOWN   = 0,
      RASQAL_QUERY_VERB_SELECT    = 1,
      RASQAL_QUERY_VERB_CONSTRUCT = 2,
      RASQAL_QUERY_VERB_DESCRIBE  = 3,
      RASQAL_QUERY_VERB_ASK       = 4,
      RASQAL_QUERY_VERB_DELETE    = 5,
      RASQAL_QUERY_VERB_INSERT    = 6,

      /* internal */
      RASQAL_QUERY_VERB_LAST=RASQAL_QUERY_VERB_INSERT
    } rasqal_query_verb;

Query main operation verbs describing the major type of query being performed.

`RASQAL_QUERY_VERB_UNKNOWN` | Internal
`RASQAL_QUERY_VERB_SELECT` | RDQL/SPARQL query select verb.
`RASQAL_QUERY_VERB_CONSTRUCT` | SPARQL query construct verb.
`RASQAL_QUERY_VERB_DESCRIBE` | SPARQL query describe verb.
`RASQAL_QUERY_VERB_ASK` | SPARQL query ask verb.
`RASQAL_QUERY_VERB_DELETE` | LAQRS query delete verb.
`RASQAL_QUERY_VERB_INSERT` | LAQRS query insert verb.
`RASQAL_QUERY_VERB_LAST` | Internal

### rasqal_query

    rasqal_graph_query* query;

Rasqal query class.

### rasqal_new_query ()

    rasqal_query*       rasqal_new_query                    (rasqal_world *world,
                                                             const char *name,
                                                             unsigned char *uri);

Constructor - create a new rasqal_query object.

A query language can be named or identified by a URI, either of which is optional. The default query language will be used if both are NULL. rasqal_languages_enumerate returns information on the known names, labels and URIs.

`world` : | rasqal_world object
`name` : | the query language name (or NULL)
`uri` : | raptor_uri language uri (or NULL)
Returns : | a new rasqal_query object or NULL on failure

### rasqal_free_query ()

    void                rasqal_free_query                   (rasqal_query *query);

Destructor - destroy a rasqal_query object.

`query` : | rasqal_query object

### rasqal_query_add_data_graph ()

    int                 rasqal_query_add_data_graph         (rasqal_query *query,
                                                             raptor_uri *uri,
                                                             raptor_uri *name_uri,
                                                             int flags);

Add a data graph to the query.

named_uri must be given if flags RASQAL_DATA_GRAPH_NAMED is set. It is the name of the graph and also used as the base URI when resolving any relative URIs for the graph in uri.

`query` : | rasqal_query query object
`uri` : | raptor_uri source uri for retrieval
`name_uri` : | raptor_uri name uri (or NULL)
`flags` : | RASQAL_DATA_GRAPH_NAMED or RASQAL_DATA_GRAPH_BACKGROUND
Returns : | non-0 on failure

### rasqal_query_add_prefix ()

    int                 rasqal_query_add_prefix             (rasqal_query *query,
                                                             rasqal_prefix *prefix);

Add a namespace prefix to the query.

If the prefix has already been used, the old URI will be overridden.

`query` : | rasqal_query query object
`prefix` : | rasqal_prefix namespace prefix, URI
Returns : | non-0 on failure

### rasqal_query_add_variable ()

    int                 rasqal_query_add_variable           (rasqal_query *query,
                                                             rasqal_variable *var);

Add a binding variable to the query.

See also rasqal_query_set_variable which assigns or removes a value to a previously added variable in the query.

`query` : | rasqal_query query object
`var` : | rasqal_variable variable
Returns : | non-0 on failure

### rasqal_query_execute ()

    rasqal_query_results* rasqal_query_execute              (rasqal_query *query);

Excute a query - run and return results.

`query` : | the rasqal_query object
Returns : | a rasqal_query_results structure or NULL on failure.

### rasqal_query_get_all_variable_sequence ()

    raptor_sequence*    rasqal_query_get_all_variable_sequence
                                                            (rasqal_query *query);

Get the sequence of all variables mentioned in the query.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_variable pointers.

### rasqal_query_get_anonymous_variable_sequence ()

    raptor_sequence*    rasqal_query_get_anonymous_variable_sequence
                                                            (rasqal_query *query);

Get the sequence of anonymous variables mentioned in the query.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_variable pointers.

### rasqal_query_get_bound_variable_sequence ()

    raptor_sequence*    rasqal_query_get_bound_variable_sequence
                                                            (rasqal_query *query);

Get the sequence of variables to bind in the query.

This returns the sequence of variables that are explicitly chosen via SELECT in RDQL, SPARQL. Or all variables mentioned with SELECT *

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_variable pointers.

### rasqal_query_get_construct_triple ()

    rasqal_triple*      rasqal_query_get_construct_triple   (rasqal_query *query,
                                                             int idx);

Get a triple in the sequence of construct triples.

`query` : | rasqal_query query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_triple pointer or NULL if out of the sequence range

### rasqal_query_get_construct_triples_sequence ()

    raptor_sequence*    rasqal_query_get_construct_triples_sequence
                                                            (rasqal_query *query);

Get the sequence of triples for a construct.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_triple pointers.

### rasqal_query_get_data_graph ()

    rasqal_data_graph*  rasqal_query_get_data_graph         (rasqal_query *query,
                                                             int idx);

Get a rasqal_data_graph* in the sequence of data_graphs.

`query` : | rasqal_query query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_data_graph pointer or NULL if out of the sequence range

### rasqal_query_get_data_graph_sequence ()

    raptor_sequence*    rasqal_query_get_data_graph_sequence
                                                            (rasqal_query *query);

Get the sequence of data_graph URIs.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of raptor_uri pointers.

### rasqal_query_get_distinct ()

    int                 rasqal_query_get_distinct           (rasqal_query *query);

Get the query distinct mode

See `rasqal_query_set_distinct()` for the distinct modes.

`query` : | rasqal_query query object
Returns : | non-0 if the results should be distinct

### rasqal_query_get_explain ()

    int                 rasqal_query_get_explain            (rasqal_query *query);

Get the query explain results flag.

`query` : | rasqal_query query object
Returns : | non-0 if the results should be explain

### rasqal_query_get_group_condition ()

    rasqal_expression*  rasqal_query_get_group_condition    (rasqal_query *query,
                                                             int idx);

Get a query grouping expression in the sequence of query grouping conditions.

`query` : | rasqal_query query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_expression pointer or NULL if out of the sequence range

### rasqal_query_get_group_conditions_sequence ()

    raptor_sequence*    rasqal_query_get_group_conditions_sequence
                                                            (rasqal_query *query);

Get the sequence of query grouping conditions.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_expression pointers.

### rasqal_query_get_graph_pattern ()

    rasqal_graph_pattern* rasqal_query_get_graph_pattern    (rasqal_query *query,
                                                             int idx);

Get a graph_pattern in the sequence of graph_pattern expressions in the top query graph pattern.

`query` : | rasqal_query query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_graph_pattern pointer or NULL if out of the sequence range

### rasqal_query_get_graph_pattern_sequence ()

    raptor_sequence*    rasqal_query_get_graph_pattern_sequence
                                                            (rasqal_query *query);

Get the sequence of graph_patterns expressions inside the top query graph pattern.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_graph_pattern pointers.

### rasqal_query_get_label ()

    const char*         rasqal_query_get_label              (rasqal_query *query);

Get a readable label for the query language.

`query` : | rasqal_query query object
Returns : | shared string label value

### rasqal_query_get_limit ()

    int                 rasqal_query_get_limit              (rasqal_query *query);

Get the query-specified limit on results.

This is the limit given in the query on the number of results allowed.

`query` : | rasqal_query query object
Returns : | integer >=0 if a limit is given, otherwise <0

### rasqal_query_get_name ()

    const char*         rasqal_query_get_name               (rasqal_query *query);

Get a short name for the query language.

`query` : | rasqal_query query object
Returns : | shared string label value

### rasqal_query_get_offset ()

    int                 rasqal_query_get_offset             (rasqal_query *query);

Get the query-specified offset on results.

This is the offset given in the query on the number of results allowed.

`query` : | rasqal_query query object
Returns : | integer >=0 if a offset is given, otherwise <0

### rasqal_query_get_order_condition ()

    rasqal_expression*  rasqal_query_get_order_condition    (rasqal_query *query,
                                                             int idx);

Get a query ordering expression in the sequence of query ordering conditions.

`query` : | rasqal_query query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_expression pointer or NULL if out of the sequence range

### rasqal_query_get_order_conditions_sequence ()

    raptor_sequence*    rasqal_query_get_order_conditions_sequence
                                                            (rasqal_query *query);

Get the sequence of query ordering conditions.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_expression pointers.

### rasqal_query_get_prefix ()

    rasqal_prefix*      rasqal_query_get_prefix             (rasqal_query *query,
                                                             int idx);

Get a prefix in the sequence of namespsace prefixes in the query.

`query` : | rasqal_query query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_prefix pointer or NULL if out of the sequence range

### rasqal_query_get_prefix_sequence ()

    raptor_sequence*    rasqal_query_get_prefix_sequence    (rasqal_query *query);

Get the sequence of namespace prefixes in the query.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_prefix pointers.

### rasqal_query_get_query_graph_pattern ()

    rasqal_graph_pattern* rasqal_query_get_query_graph_pattern
                                                            (rasqal_query *query);

Get the top query graph pattern.

`query` : | rasqal_query query object
Returns : | a rasqal_graph_pattern of the top query graph pattern

### rasqal_query_get_triple ()

    rasqal_triple*      rasqal_query_get_triple             (rasqal_query *query,
                                                             int idx);

Get a triple in the sequence of matching triples in the query.

`query` : | rasqal_query query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_triple pointer or NULL if out of the sequence range

### rasqal_query_get_triple_sequence ()

    raptor_sequence*    rasqal_query_get_triple_sequence    (rasqal_query *query);

Get the sequence of matching triples in the query.

`query` : | rasqal_query query object
Returns : | a raptor_sequence of rasqal_triple pointers.

### rasqal_query_get_user_data ()

    void*               rasqal_query_get_user_data          (rasqal_query *query);

Get query user data.

`query` : | rasqal_query
Returns : | user data as set by rasqal_query_set_user_data

### rasqal_query_get_variable ()

    rasqal_variable*    rasqal_query_get_variable           (rasqal_query *query,
                                                             int idx);

Get a variable in the sequence of variables to bind.

`query` : | rasqal_query query object
`idx` : | index into the sequence (0 or larger)
Returns : | a rasqal_variable pointer or NULL if out of the sequence range

### rasqal_query_get_verb ()

    rasqal_query_verb   rasqal_query_get_verb               (rasqal_query *query);

Get the query verb.

`query` : | rasqal_query
Returns : | the operating verb of the query of type rasqal_query_verb

### rasqal_query_get_wildcard ()

    int                 rasqal_query_get_wildcard           (rasqal_query *query);

Get the query verb is wildcard flag.

`query` : | rasqal_query
Returns : | non-0 if the query verb was a wildcard (such as SELECT *)

### rasqal_query_has_variable ()

    int                 rasqal_query_has_variable           (rasqal_query *query,
                                                             unsigned char *name);

Find if the named variable is in the sequence of variables to bind.

`query` : | rasqal_query query object
`name` : | variable name
Returns : | non-0 if the variable name was found.

### rasqal_query_prepare ()

    int                 rasqal_query_prepare                (rasqal_query *query,
                                                             unsigned char *query_string,
                                                             raptor_uri *base_uri);

Prepare a query - typically parse it.

Some query languages may require a base URI to resolve any relative URIs in the query string. If this is not given, the current directory in the filesystem is used as the base URI.

The query string may be NULL in which case it is not parsed and the query parts may be created by API calls such as rasqal_query_add_source etc.

`query` : | the rasqal_query object
`query_string` : | the query string (or NULL)
`base_uri` : | base URI of query string (optional)
Returns : | non-0 on failure.

### rasqal_query_print ()

    void                rasqal_query_print                  (rasqal_query *query,
                                                             FILE *fh);

Print a query in a debug format.

`query` : | the rasqal_query object
`fh` : | the FILE* handle to print to.

### rasqal_query_graph_pattern_visit ()

    void                rasqal_query_graph_pattern_visit    (rasqal_query *query,
                                                             rasqal_graph_pattern_visit_fn visit_fn,
                                                             void *data);

Visit all graph patterns in a query with a user function `visit_fn`.

See also `rasqal_graph_pattern_visit()`.

`query` : | query
`visit_fn` : | user function to operate on
`data` : | user data to pass to function

### rasqal_query_set_default_generate_bnodeid_parameters ()

    void                rasqal_query_set_default_generate_bnodeid_parameters
                                                            (rasqal_query *rdf_query,
                                                             char *prefix,
                                                             int base);

Sets the parameters for the default algorithm used to generate blank node IDs. The default algorithm uses both `prefix` and `base` to generate a new identifier. The exact identifier generated is not guaranteed to be a strict concatenation of `prefix` and `base` but will use both parts.

For finer control of the generated identifiers, use `rasqal_set_default_generate_bnodeid_handler()`

If prefix is NULL, the default prefix is used (currently "bnodeid") If base is less than 1, it is initialised to 1.

`rdf_query` : | rasqal_query object
`prefix` : | prefix string
`base` : | integer base identifier

### rasqal_query_set_distinct ()

    void                rasqal_query_set_distinct           (rasqal_query *query,
                                                             int distinct_mode);

Set the query distinct results mode.

The allowed `distinct_mode` values are: 0 if not given 1 if DISTINCT: ensure solutions are unique 2 if SPARQL REDUCED: permit elimination of some non-unique solutions

`query` : | rasqal_query query object
`distinct_mode` : | distinct mode

### rasqal_query_set_explain ()

    void                rasqal_query_set_explain            (rasqal_query *query,
                                                             int is_explain);

Set the query explain results flag.

`query` : | rasqal_query query object
`is_explain` : | non-0 if explain

### rasqal_query_set_error_handler ()

    void                rasqal_query_set_error_handler      (rasqal_query *query,
                                                             void *user_data,
                                                             raptor_message_handler handler);

Set the query error handling function.

The function will receive callbacks when the query fails.

`query` : | the query
`user_data` : | user data to pass to function
`handler` : | pointer to the function

### rasqal_query_set_fatal_error_handler ()

    void                rasqal_query_set_fatal_error_handler
                                                            (rasqal_query *query,
                                                             void *user_data,
                                                             raptor_message_handler handler);

Set the query error handling function.

The function will receive callbacks when the query fails.

`query` : | the query
`user_data` : | user data to pass to function
`handler` : | pointer to the function

### rasqal_query_set_generate_bnodeid_handler ()

    void                rasqal_query_set_generate_bnodeid_handler
                                                            (rasqal_query *query,
                                                             void *user_data,
                                                             rasqal_generate_bnodeid_handler handler);

Set the generate blank node ID handler function for the query.

Sets the function to generate blank node IDs for the query. The handler is called with a pointer to the rasqal_query, the `user_data` pointer and a user_bnodeid which is the value of a user-provided blank node identifier (may be NULL). It can either be returned directly as the generated value when present or modified. The passed in value must be `free()`d if it is not used.

If handler is NULL, the default method is used

`query` : | rasqal_query query object
`user_data` : | user data pointer for callback
`handler` : | generate blank ID callback function

### rasqal_query_set_limit ()

    void                rasqal_query_set_limit              (rasqal_query *query,
                                                             int limit);

Set the query-specified limit on results.

This is the limit given in the query on the number of results allowed.

`query` : | rasqal_query query object
`limit` : | the limit on results, >=0 to set a limit, <0 to have no limit

### rasqal_query_set_offset ()

    void                rasqal_query_set_offset             (rasqal_query *query,
                                                             int offset);

Set the query-specified offset on results.

This is the offset given in the query on the number of results allowed.

`query` : | rasqal_query query object
`offset` : | offset for results, >=0 to set an offset, <0 to have no offset

### rasqal_query_set_user_data ()

    void                rasqal_query_set_user_data          (rasqal_query *query,
                                                             void *user_data);

Set the query user data.

`query` : | rasqal_query
`user_data` : | some user data to associate with the query

### rasqal_query_set_variable ()

    int                 rasqal_query_set_variable           (rasqal_query *query,
                                                             unsigned char *name,
                                                             rasqal_literal *value);

Add a binding variable to the query.

See also rasqal_query_add_variable which adds a new binding variable and must be called before this method is invoked.

`query` : | rasqal_query query object
`name` : | rasqal_variable variable
`value` : | rasqal_literal value to set or NULL
Returns : | non-0 on failure

### rasqal_query_set_warning_handler ()

    void                rasqal_query_set_warning_handler    (rasqal_query *query,
                                                             void *user_data,
                                                             raptor_message_handler handler);

Set the query warning handling function.

The function will receive callbacks when the query gives a warning.

`query` : | the query
`user_data` : | user data to pass to function
`handler` : | pointer to the function

### rasqal_query_verb_as_string ()

    const char*         rasqal_query_verb_as_string         (rasqal_query_verb verb);

Get a string for the query verb.

`verb` : | the rasqal_query_verb verb of the query
Returns : | pointer to a shared string label for the query verb

### rasqal_query_write ()

    int                 rasqal_query_write                  (raptor_iostream *iostr,
                                                             rasqal_query *query,
                                                             raptor_uri *format_uri,
                                                             raptor_uri *base_uri);

Write a query to an iostream in a specified format.

The supported URIs for the format_uri are:

Default: SPARQL Query Language 2006-04-06 http://www.w3.org/TR/2006/CR-rdf-sparql-query-20060406/

`iostr` : | raptor_iostream to write the query to
`query` : | rasqal_query pointer.
`format_uri` : | raptor_uri describing the format to write (or NULL for default)
`base_uri` : | raptor_uri base URI of the output format
Returns : | non-0 on failure

### rasqal_query_iostream_write_escaped_counted_string ()

    int                 rasqal_query_iostream_write_escaped_counted_string
                                                            (rasqal_query *query,
                                                             raptor_iostream *iostr,
                                                             unsigned char *string,
                                                             size_t len);

Write a string to an iostream in escaped form suitable for the query string.

`query` : | rasqal_query object
`iostr` : | raptor_iostream to write the escaped string to
`string` : | string to escape
`len` : | Length of string to escape
Returns : | non-0 on failure

### rasqal_query_escape_counted_string ()

    unsigned char*      rasqal_query_escape_counted_string  (rasqal_query *query,
                                                             unsigned char *string,
                                                             size_t len,
                                                             size_t *output_len_p);

Convert a string into an escaped form suitable for the query string.

The returned string must be freed by the caller with `rasqal_free_memory()`

`query` : | rasqal_query object
`string` : | string to escape
`len` : | Length of string to escape
`output_len_p` : | Pointer to store length of output string (or NULL)
Returns : | the escaped string or NULL on failure.

### rasqal_query_set_feature ()

    int                 rasqal_query_set_feature            (rasqal_query *query,
                                                             rasqal_feature feature,
                                                             int value);

Set various query features.

The allowed features are available via `rasqal_features_enumerate()`.

`query` : | rasqal_query query object
`feature` : | feature to set from enumerated rasqal_feature values
`value` : | integer feature value
Returns : | non 0 on failure or if the feature is unknown

### rasqal_query_set_feature_string ()

    int                 rasqal_query_set_feature_string     (rasqal_query *query,
                                                             rasqal_feature feature,
                                                             unsigned char *value);

Set query features with string values.

The allowed features are available via `rasqal_features_enumerate()`. If the feature type is integer, the value is interpreted as an integer.

`query` : | rasqal_query query object
`feature` : | feature to set from enumerated rasqal_feature values
`value` : | feature value
Returns : | non 0 on failure or if the feature is unknown

### rasqal_query_get_feature ()

    int                 rasqal_query_get_feature            (rasqal_query *query,
                                                             rasqal_feature feature);

Get various query features.

The allowed features are available via `rasqal_features_enumerate()`.

Note: no feature value is negative

`query` : | rasqal_query query object
`feature` : | feature to get value
Returns : | feature value or < 0 for an illegal feature

### rasqal_query_get_feature_string ()

    const unsigned char* rasqal_query_get_feature_string    (rasqal_query *query,
                                                             rasqal_feature feature);

Get query features with string values.

The allowed features are available via `rasqal_features_enumerate()`. If a string is returned, it must be freed by the caller.

`query` : | rasqal_query query object
`feature` : | feature to get value
Returns : | feature value or NULL for an illegal feature or no value