Query Results

Query Results — Query results as variable bindings, boolean or RDF graphs.

Synopsis

typedef             rasqal_query_results;
rasqal_query_results * rasqal_new_query_results         (rasqal_world *world,
                                                         rasqal_query *query,
                                                         rasqal_query_results_type type,
                                                         rasqal_variables_table *vars_table);
rasqal_query_results * rasqal_new_query_results2        (rasqal_world *world,
                                                         rasqal_query *query,
                                                         rasqal_query_results_type type);
rasqal_query_results * rasqal_new_query_results_from_string
                                                        (rasqal_world *world,
                                                         rasqal_query_results_type type,
                                                         raptor_uri *base_uri,
                                                         const char *string,
                                                         size_t string_len);
void                rasqal_free_query_results           (rasqal_query_results *query_results);
int                 rasqal_query_results_add_row        (rasqal_query_results *query_results,
                                                         rasqal_row *row);
int                 rasqal_query_results_finished       (rasqal_query_results *query_results);
const unsigned char * rasqal_query_results_get_binding_name
                                                        (rasqal_query_results *query_results,
                                                         int offset);
rasqal_literal *    rasqal_query_results_get_binding_value
                                                        (rasqal_query_results *query_results,
                                                         int offset);
rasqal_literal *    rasqal_query_results_get_binding_value_by_name
                                                        (rasqal_query_results *query_results,
                                                         const char *name);
int                 rasqal_query_results_get_bindings   (rasqal_query_results *query_results,
                                                         const unsigned char ***names,
                                                         rasqal_literal ***values);
int                 rasqal_query_results_get_bindings_count
                                                        (rasqal_query_results *query_results);
int                 rasqal_query_results_get_boolean    (rasqal_query_results *query_results);
int                 rasqal_query_results_get_count      (rasqal_query_results *query_results);
rasqal_query *      rasqal_query_results_get_query      (rasqal_query_results *query_results);
raptor_statement *  rasqal_query_results_get_triple     (rasqal_query_results *query_results);
rasqal_row *        rasqal_query_results_get_row_by_offset
                                                        (rasqal_query_results *query_results,
                                                         int result_offset);
rasqal_query_results_type rasqal_query_results_get_type (rasqal_query_results *query_results);
int                 rasqal_query_results_is_bindings    (rasqal_query_results *query_results);
int                 rasqal_query_results_is_boolean     (rasqal_query_results *query_results);
int                 rasqal_query_results_is_graph       (rasqal_query_results *query_results);
int                 rasqal_query_results_is_syntax      (rasqal_query_results *query_results);
int                 rasqal_query_results_next           (rasqal_query_results *query_results);
int                 rasqal_query_results_next_triple    (rasqal_query_results *query_results);
int                 rasqal_query_results_read           (raptor_iostream *iostr,
                                                         rasqal_query_results *results,
                                                         const char *name,
                                                         const char *mime_type,
                                                         raptor_uri *format_uri,
                                                         raptor_uri *base_uri);
int                 rasqal_query_results_write          (raptor_iostream *iostr,
                                                         rasqal_query_results *results,
                                                         const char *name,
                                                         const char *mime_type,
                                                         raptor_uri *format_uri,
                                                         raptor_uri *base_uri);
enum                rasqal_query_results_type;
const char *        rasqal_query_results_type_label     (rasqal_query_results_type type);
int                 rasqal_query_results_rewind         (rasqal_query_results *query_results);

Description

A query results object is only ever constructed by the internal query engine evaluating a rasqal_query with rasqal_query_execute(). It provides interface to the multiple types of result supported.

There are a large set of methods for returning all or parts of a variable binding query result including the names, values or individuals. A boolean result is straightforward to get with rasqal_query_results_get_boolean() and an RDF graph returns a sequence of raptor triples than can be easily passed to the Raptor library for serializing to a syntax.

Details

rasqal_query_results

rasqal_graph_query_results* query_results;

Rasqal query results class.

rasqal_new_query_results ()

rasqal_query_results * rasqal_new_query_results         (rasqal_world *world,
                                                         rasqal_query *query,
                                                         rasqal_query_results_type type,
                                                         rasqal_variables_table *vars_table);

Constructor - create a new query results set

Deprecated for rasqal_new_query_results2() that loses the unused argument.

The query may be NULL for result set objects that are standalone and not attached to any particular query

world :

 rasqal world object

query :

 query object (or NULL)

type :

 query results (expected) type

vars_table :

 This parameter is *IGNORED*

Returns :

 a new query result object or NULL on failure

rasqal_new_query_results2 ()

rasqal_query_results * rasqal_new_query_results2        (rasqal_world *world,
                                                         rasqal_query *query,
                                                         rasqal_query_results_type type);

Constructor - create a new query results set

The query may be NULL for result set objects that are standalone and not attached to any particular query

world :

 rasqal world object

query :

 query object (or NULL)

type :

 query results (expected) type

Returns :

 a new query result object or NULL on failure

rasqal_new_query_results_from_string ()

rasqal_query_results * rasqal_new_query_results_from_string
                                                        (rasqal_world *world,
                                                         rasqal_query_results_type type,
                                                         raptor_uri *base_uri,
                                                         const char *string,
                                                         size_t string_len);

Constructor - create a new query results set from a results format string

world :

 rasqal world object

type :

 query results (expected) type; typically RASQAL_QUERY_RESULTS_BINDINGS

base_uri :

 base URI of query results format (or NULL)

string :

 query results string

string_len :

 length of string (or 0 to calculate it here)

Returns :

 a new query result object or NULL on failure

rasqal_free_query_results ()

void                rasqal_free_query_results           (rasqal_query_results *query_results);

Destructor - destroy a rasqal_query_results.

query_results :

 rasqal_query_results object

rasqal_query_results_add_row ()

int                 rasqal_query_results_add_row        (rasqal_query_results *query_results,
                                                         rasqal_row *row);

Add a query result row to the sequence of result rows

query_results :

 query results object

row :

 query result row

Returns :

 non-0 on failure

rasqal_query_results_finished ()

int                 rasqal_query_results_finished       (rasqal_query_results *query_results);

Find out if binding results are exhausted.

query_results :

 rasqal_query_results query_results

Returns :

 non-0 if results are finished or query failed

rasqal_query_results_get_binding_name ()

const unsigned char * rasqal_query_results_get_binding_name
                                                        (rasqal_query_results *query_results,
                                                         int offset);

Get binding name for the current result.

query_results :

 rasqal_query_results query_results

offset :

 offset of binding name into array of known names

Returns :

 a pointer to a shared copy of the binding name or NULL on failure

rasqal_query_results_get_binding_value ()

rasqal_literal *    rasqal_query_results_get_binding_value
                                                        (rasqal_query_results *query_results,
                                                         int offset);

Get one binding value for the current result.

query_results :

 rasqal_query_results query_results

offset :

 offset of binding name into array of known names

Returns :

 a pointer to a shared rasqal_literal binding value or NULL on failure

rasqal_query_results_get_binding_value_by_name ()

rasqal_literal *    rasqal_query_results_get_binding_value_by_name
                                                        (rasqal_query_results *query_results,
                                                         const char *name);

Get one binding value for a given name in the current result.

query_results :

 rasqal_query_results query_results

name :

 variable name

Returns :

 a pointer to a shared rasqal_literal binding value or NULL on failure

rasqal_query_results_get_bindings ()

int                 rasqal_query_results_get_bindings   (rasqal_query_results *query_results,
                                                         const unsigned char ***names,
                                                         rasqal_literal ***values);

Get all binding names, values for current result.

If names is not NULL, it is set to the address of a shared array of names of the bindings (an output parameter). These names are shared and must not be freed by the caller

If values is not NULL, it is set to the address of a shared array of rasqal_literal* binding values. These values are shaerd and must not be freed by the caller.

query_results :

 rasqal_query_results query_results

names :

 pointer to an array of binding names (or NULL)

values :

 pointer to an array of binding value rasqal_literal (or NULL)

Returns :

 non-0 if the assignment failed

rasqal_query_results_get_bindings_count ()

int                 rasqal_query_results_get_bindings_count
                                                        (rasqal_query_results *query_results);

Get the number of bound variables in the result.

query_results :

 rasqal_query_results query_results

Returns :

 <0 if failed or results exhausted

rasqal_query_results_get_boolean ()

int                 rasqal_query_results_get_boolean    (rasqal_query_results *query_results);

Get boolean query result.

The return value is only meaningful if this is a boolean query result - see rasqal_query_results_is_boolean()

query_results :

 rasqal_query_results query_results

Returns :

 boolean query result - >0 is true, 0 is false, <0 on error

rasqal_query_results_get_count ()

int                 rasqal_query_results_get_count      (rasqal_query_results *query_results);

Get number of bindings so far.

query_results :

 rasqal_query_results query_results

Returns :

 number of bindings found so far or < 0 on failure

rasqal_query_results_get_query ()

rasqal_query *      rasqal_query_results_get_query      (rasqal_query_results *query_results);

Get thq query associated with this query result

query_results :

 rasqal_query_results object

Returns :

 shared pointer to query object

rasqal_query_results_get_triple ()

raptor_statement *  rasqal_query_results_get_triple     (rasqal_query_results *query_results);

Get the current triple in the result.

The return value is a shared raptor_statement.

query_results :

 rasqal_query_results query_results

Returns :

 raptor_statement or NULL if failed or results exhausted

rasqal_query_results_get_row_by_offset ()

rasqal_row *        rasqal_query_results_get_row_by_offset
                                                        (rasqal_query_results *query_results,
                                                         int result_offset);

Get stored result row by an offset

The result_offset index is 0-indexed into the subset of results constrained by any query limit and offset.

query_results :

 query result

result_offset :

 index into result rows

Returns :

 row or NULL if result_offset is out of range

rasqal_query_results_get_type ()

rasqal_query_results_type rasqal_query_results_get_type (rasqal_query_results *query_results);

Get query results type

query_results :

 rasqal_query_results object

Returns :

 non-0 if true

rasqal_query_results_is_bindings ()

int                 rasqal_query_results_is_bindings    (rasqal_query_results *query_results);

Test if rasqal_query_results is variable bindings format.

query_results :

 rasqal_query_results object

Returns :

 non-0 if true

rasqal_query_results_is_boolean ()

int                 rasqal_query_results_is_boolean     (rasqal_query_results *query_results);

Test if rasqal_query_results is boolean format.

query_results :

 rasqal_query_results object

Returns :

 non-0 if true

rasqal_query_results_is_graph ()

int                 rasqal_query_results_is_graph       (rasqal_query_results *query_results);

Test if rasqal_query_results is RDF graph format.

query_results :

 rasqal_query_results object

Returns :

 non-0 if true

rasqal_query_results_is_syntax ()

int                 rasqal_query_results_is_syntax      (rasqal_query_results *query_results);

Test if the rasqal_query_results is a syntax.

Many of the query results may be formatted as a syntax using the rasqal_query_formatter class however this function returns true if a syntax result was specifically requested.

query_results :

 rasqal_query_results object

Returns :

 non-0 if true

rasqal_query_results_next ()

int                 rasqal_query_results_next           (rasqal_query_results *query_results);

Move to the next result.

query_results :

 rasqal_query_results query_results

Returns :

 non-0 if failed or results exhausted

rasqal_query_results_next_triple ()

int                 rasqal_query_results_next_triple    (rasqal_query_results *query_results);

Move to the next triple result.

query_results :

 rasqal_query_results query_results

Returns :

 non-0 if failed or results exhausted

rasqal_query_results_read ()

int                 rasqal_query_results_read           (raptor_iostream *iostr,
                                                         rasqal_query_results *results,
                                                         const char *name,
                                                         const char *mime_type,
                                                         raptor_uri *format_uri,
                                                         raptor_uri *base_uri);

Read the query results from an iostream in a format.

This uses the rasqal_query_results_formatter class and the rasqal_query_results_formatter_read() method to perform the formatting.

See rasqal_world_get_query_results_format_description() for obtaining the supported format URIs at run time.

iostr :

 raptor_iostream to read the query from

results :

 rasqal_query_results query results format

name :

 format name (or NULL)

mime_type :

 format mime type (or NULL)

format_uri :

 raptor_uri describing the format to read (or NULL for default)

base_uri :

 raptor_uri base URI of the input format

Returns :

 non-0 on failure

rasqal_query_results_write ()

int                 rasqal_query_results_write          (raptor_iostream *iostr,
                                                         rasqal_query_results *results,
                                                         const char *name,
                                                         const char *mime_type,
                                                         raptor_uri *format_uri,
                                                         raptor_uri *base_uri);

Write the query results to an iostream in a format.

This uses the rasqal_query_results_formatter class and the rasqal_query_results_formatter_write() method to perform the formatting.

Note that after calling this method, the query results will be empty and rasqal_query_results_finished() will return true (non-0)

See rasqal_world_get_query_results_format_description() for obtaining the supported format names, mime_types and URIs at run time.

iostr :

 raptor_iostream to write the query to

results :

 rasqal_query_results query results format

name :

 format name (or NULL)

mime_type :

 format mime type (or NULL)

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

enum rasqal_query_results_type

typedef enum {
  RASQAL_QUERY_RESULTS_BINDINGS,
  RASQAL_QUERY_RESULTS_BOOLEAN,
  RASQAL_QUERY_RESULTS_GRAPH,
  RASQAL_QUERY_RESULTS_SYNTAX,
  RASQAL_QUERY_RESULTS_UNKNOWN,
  RASQAL_QUERY_RESULTS_LAST = RASQAL_QUERY_RESULTS_UNKNOWN
} rasqal_query_results_type;

Query result type.

RASQAL_QUERY_RESULTS_BINDINGS

 variable binding

RASQAL_QUERY_RESULTS_BOOLEAN

 a single boolean

RASQAL_QUERY_RESULTS_GRAPH

 an RDF graph

RASQAL_QUERY_RESULTS_SYNTAX

 a syntax

RASQAL_QUERY_RESULTS_UNKNOWN

 unknown type

RASQAL_QUERY_RESULTS_LAST

 internal

rasqal_query_results_type_label ()

const char *        rasqal_query_results_type_label     (rasqal_query_results_type type);

Get a label for a query results type

type :

 rasqal_query_results_type type

Returns :

 label or NULL on failure (invalid type)

rasqal_query_results_rewind ()

int                 rasqal_query_results_rewind         (rasqal_query_results *query_results);

Rewind stored query results to start

This requires rasqal_query_set_store_results() to be called before query execution.

query_results :

 rasqal_query_results query_results

Returns :

 non-0 if rewinding is not available when results are not stored
Generated by GTK-Doc V1.18