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,
                                                         const char *uri);
void                rasqal_free_query                   (rasqal_query *query);
int                 rasqal_query_add_data_graph         (rasqal_query *query,
                                                         rasqal_data_graph *data_graph);
int                 rasqal_query_add_data_graphs        (rasqal_query *query,
                                                         raptor_sequence *data_graphs);
int                 rasqal_query_add_prefix             (rasqal_query *query,
                                                         rasqal_prefix *prefix);
int                 rasqal_query_add_variable           (rasqal_query *query,
                                                         rasqal_variable *var);
int                 rasqal_query_dataset_contains_named_graph
                                                        (rasqal_query *query,
                                                         raptor_uri *graph_uri);
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);
rasqal_row *        rasqal_query_get_bindings_row       (rasqal_query *query,
                                                         int idx);
raptor_sequence *   rasqal_query_get_bindings_rows_sequence
                                                        (rasqal_query *query);
rasqal_variable *   rasqal_query_get_bindings_variable  (rasqal_query *query,
                                                         int idx);
raptor_sequence *   rasqal_query_get_bindings_variables_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);
raptor_sequence *   rasqal_query_get_describe_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);
rasqal_expression * rasqal_query_get_having_condition   (rasqal_query *query,
                                                         int idx);
raptor_sequence *   rasqal_query_get_having_conditions_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_variable2          (rasqal_query *query,
                                                         rasqal_variable_type type,
                                                         const char *name);
int                 rasqal_query_has_variable           (rasqal_query *query,
                                                         const char *name);
int                 rasqal_query_prepare                (rasqal_query *query,
                                                         const char *query_string,
                                                         raptor_uri *base_uri);
int                 rasqal_query_print                  (rasqal_query *query,
                                                         FILE *fh);
int                 rasqal_query_graph_pattern_visit2   (rasqal_query *query,
                                                         rasqal_graph_pattern_visit_fn visit_fn,
                                                         void *data);
void                rasqal_query_graph_pattern_visit    (rasqal_query *query,
                                                         rasqal_graph_pattern_visit_fn visit_fn,
                                                         void *data);
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_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_variable2          (rasqal_query *query,
                                                         rasqal_variable_type type,
                                                         const char *name,
                                                         rasqal_literal *value);
int                 rasqal_query_set_variable           (rasqal_query *query,
                                                         const char *name,
                                                         rasqal_literal *value);
int                 rasqal_query_set_store_results      (rasqal_query *query,
                                                         int store_results);
void                rasqal_query_set_wildcard           (rasqal_query *query,
                                                         int wildcard);
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,
                                                         const unsigned char *string,
                                                         size_t len);
unsigned char *     rasqal_query_escape_counted_string  (rasqal_query *query,
                                                         const 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,
                                                         const 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);
rasqal_query_results_type rasqal_query_get_result_type  (rasqal_query *query);
rasqal_update_operation * rasqal_query_get_update_operation
                                                        (rasqal_query *query,
                                                         int idx);
raptor_sequence *   rasqal_query_get_update_operations_sequence
                                                        (rasqal_query *query);

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,
  RASQAL_QUERY_VERB_UPDATE    = 7,

  /* internal */
  RASQAL_QUERY_VERB_LAST = RASQAL_QUERY_VERB_UPDATE
} rasqal_query_verb;

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

RASQAL_QUERY_VERB_UNKNOWN

Internal

RASQAL_QUERY_VERB_SELECT

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_UPDATE

SPARQL 1.1 (draft) update operation

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,
                                                         const 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_world_get_query_language_description returns the description of the known names, labels, MIME types 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,
                                                         rasqal_data_graph *data_graph);

Add a data graph to the query.

query :

rasqal_query query object

data_graph :

data graph

Returns :

non-0 on failure

rasqal_query_add_data_graphs ()

int                 rasqal_query_add_data_graphs        (rasqal_query *query,
                                                         raptor_sequence *data_graphs);

Add a set of data graphs to the query.

The objects in the passed-in data_graphs sequence becomes owne by the query. The data_graphs sequence itself is freed and must not be used after this call.

query :

rasqal_query query object

data_graphs :

sequence of rasqal_data_graph

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 projected (named) 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_dataset_contains_named_graph ()

int                 rasqal_query_dataset_contains_named_graph
                                                        (rasqal_query *query,
                                                         raptor_uri *graph_uri);

Test if the query dataset contains a named graph

query :

rasqal_query query object

graph_uri :

query URI

Returns :

non-0 if the dataset contains a named graph

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_bindings_row ()

rasqal_row *        rasqal_query_get_bindings_row       (rasqal_query *query,
                                                         int idx);

Get a rasqal_row* in the sequence of BINDINGS block result rows

query :

rasqal_query query object

idx :

index into the sequence (0 or larger)

Returns :

a raptor_sequence of raptor_row pointers

rasqal_query_get_bindings_rows_sequence ()

raptor_sequence *   rasqal_query_get_bindings_rows_sequence
                                                        (rasqal_query *query);

Get the sequence of BINDINGS block result rows

query :

rasqal_query query object

Returns :

a raptor_sequence of raptor_row pointers

rasqal_query_get_bindings_variable ()

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

Get a rasqal_variable* in the sequence of BINDINGS block variables

query :

rasqal_query query object

idx :

index into the sequence (0 or larger)

Returns :

a raptor_sequence of raptor_variable pointers

rasqal_query_get_bindings_variables_sequence ()

raptor_sequence *   rasqal_query_get_bindings_variables_sequence
                                                        (rasqal_query *query);

Get the sequence of BINDINGS block variables

query :

rasqal_query query object

Returns :

a raptor_sequence of raptor_variable pointers

rasqal_query_get_bound_variable_sequence ()

raptor_sequence *   rasqal_query_get_bound_variable_sequence
                                                        (rasqal_query *query);

Get the sequence of projected variables in the query.

This returns the sequence of variables that are explicitly chosen via SELECT in 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_describe_sequence ()

raptor_sequence *   rasqal_query_get_describe_sequence  (rasqal_query *query);

Get the sequence of literals described in the query.

This returns the sequence of literals (constants or variables) that are explicitly chosen via DESCRIBE in SPARQL.

query :

rasqal_query query object

Returns :

a raptor_sequence of rasqal_literal 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_having_condition ()

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

Get a query having expression in the sequence of query havinging 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_having_conditions_sequence ()

raptor_sequence *   rasqal_query_get_having_conditions_sequence
                                                        (rasqal_query *query);

Get the sequence of query having conditions.

query :

rasqal_query query object

Returns :

a raptor_sequence of rasqal_expression 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. It is only guaranteed to work after the query is prepared and before it is executed.

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 query

query :

rasqal_query query object

idx :

index into the sequence (0 or larger)

Returns :

pointer to shared rasqal_variable or NULL if out of 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_variable2 ()

int                 rasqal_query_has_variable2          (rasqal_query *query,
                                                         rasqal_variable_type type,
                                                         const char *name);

Find if the named variable of the given type is in the query

Note that looking up for any type RASQAL_VARIABLE_TYPE_UNKNOWN may a name match but for any type so in cases where the query has both a named and anonymous (extensional) variable, an arbitrary one will be returned.

query :

rasqal_query query object

type :

the variable type to match or RASQAL_VARIABLE_TYPE_UNKNOWN for any.

name :

variable name

Returns :

non-0 if the variable name was found.

rasqal_query_has_variable ()

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

Find if the named variable is in the query (of any type)

Deprecated: Use rasqal_query_has_variable2() with the variable type arg

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,
                                                         const 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 ()

int                 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.

Returns :

non-0 on failure

rasqal_query_graph_pattern_visit2 ()

int                 rasqal_query_graph_pattern_visit2   (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

Returns :

result from visit function visit_fn if it returns non-0

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.

Deprecated: use rasqal_query_graph_pattern_visit2() that returns the visit_fn status code.

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_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_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. It is only guaranteed to work after the query is prepared and before it is executed.

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_variable2 ()

int                 rasqal_query_set_variable2          (rasqal_query *query,
                                                         rasqal_variable_type type,
                                                         const char *name,
                                                         rasqal_literal *value);

Bind an existing typed variable to a value 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

type :

the variable type to match or RASQAL_VARIABLE_TYPE_UNKNOWN for any.

name :

rasqal_variable variable

value :

rasqal_literal value to set or NULL

Returns :

non-0 on failure

rasqal_query_set_variable ()

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

Bind an existing named (selected) variable to a value to the query.

Deprecated for rasqal_query_set_variable2() that includes a type arg. This function only sets named variables of type RASQAL_VARIABLE_TYPE_NORMAL

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_store_results ()

int                 rasqal_query_set_store_results      (rasqal_query *query,
                                                         int store_results);

Request that query results are stored during execution

When called after a rasqal_query_prepare(), this tells rasqal_query_execute() to execute the entire query immediately rather than generate them lazily, and store all the results in memory. The results will then be available for reading multiple times using rasqal_query_results_rewind() to move back to the start of the result object. If called after preparation, returns failure.

query :

the rasqal_query object

store_results :

store results flag

Returns :

non-0 on failure.

rasqal_query_set_wildcard ()

void                rasqal_query_set_wildcard           (rasqal_query *query,
                                                         int wildcard);

Set the query projection wildcard flag

query :

rasqal_query query object

wildcard :

wildcard

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,
                                                         const 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,
                                                         const 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,
                                                         const 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

rasqal_query_get_result_type ()

rasqal_query_results_type rasqal_query_get_result_type  (rasqal_query *query);

Get the result type expected from executing the query.

This function is only valid after rasqal_query_prepare() has been run on the query and will return RASQAL_QUERY_RESULTS_UNKNOWN if called before preparation.

query :

rasqal_query query object

Returns :

result type or RASQAL_QUERY_RESULTS_UNKNOWN if not known or on error

rasqal_query_get_update_operation ()

rasqal_update_operation * rasqal_query_get_update_operation
                                                        (rasqal_query *query,
                                                         int idx);

Get a query update operation in the sequence of update operations

query :

rasqal_query query object

idx :

index into the sequence (0 or larger)

Returns :

a rasqal_update_operation pointer or NULL if out of the sequence range

rasqal_query_get_update_operations_sequence ()

raptor_sequence *   rasqal_query_get_update_operations_sequence
                                                        (rasqal_query *query);

Get the sequence of update operations

query :

rasqal_query query object

Returns :

a raptor_sequence of rasqal_update_operation pointers.