Query results

## Query results Query results — RDF query results. |

## Synopsis

    typedef             librdf_query_results;
    librdf_stream *     librdf_query_results_as_stream      (librdf_query_results *query_results);
    int                 librdf_query_results_get_count      (librdf_query_results *query_results);
    int                 librdf_query_results_next           (librdf_query_results *query_results);
    int                 librdf_query_results_finished       (librdf_query_results *query_results);
    int                 librdf_query_results_get_bindings   (librdf_query_results *query_results,
                                                             const char ***names,
                                                             librdf_node **values);
    librdf_node *       librdf_query_results_get_binding_value
                                                            (librdf_query_results *query_results,
                                                             int offset);
    const char *        librdf_query_results_get_binding_name
                                                            (librdf_query_results *query_results,
                                                             int offset);
    librdf_node *       librdf_query_results_get_binding_value_by_name
                                                            (librdf_query_results *query_results,
                                                             const char *name);
    int                 librdf_query_results_get_bindings_count
                                                            (librdf_query_results *query_results);
    unsigned char *     librdf_query_results_to_counted_string
                                                            (librdf_query_results *query_results,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri,
                                                             size_t *length_p);
    unsigned char *     librdf_query_results_to_counted_string2
                                                            (librdf_query_results *query_results,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri,
                                                             size_t *length_p);
    unsigned char *     librdf_query_results_to_string      (librdf_query_results *query_results,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);
    unsigned char *     librdf_query_results_to_string2     (librdf_query_results *query_results,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);
    int                 librdf_query_results_to_file_handle (librdf_query_results *query_results,
                                                             FILE *handle,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);
    int                 librdf_query_results_to_file_handle2
                                                            (librdf_query_results *query_results,
                                                             FILE *handle,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);
    int                 librdf_query_results_to_file        (librdf_query_results *query_results,
                                                             const char *name,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);
    int                 librdf_query_results_to_file2       (librdf_query_results *query_results,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);
    void                librdf_free_query_results           (librdf_query_results *query_results);
    int                 librdf_query_results_is_bindings    (librdf_query_results *query_results);
    int                 librdf_query_results_is_boolean     (librdf_query_results *query_results);
    int                 librdf_query_results_is_graph       (librdf_query_results *query_results);
    int                 librdf_query_results_is_syntax      (librdf_query_results *query_results);
    int                 librdf_query_results_get_boolean    (librdf_query_results *query_results);
    librdf_query_results_formatter * librdf_new_query_results_formatter
                                                            (librdf_query_results *query_results,
                                                             const char *name,
                                                             librdf_uri *uri);
    librdf_query_results_formatter * librdf_new_query_results_formatter_by_mime_type
                                                            (librdf_query_results *query_results,
                                                             const char *mime_type);
    librdf_query_results_formatter * librdf_new_query_results_formatter2
                                                            (librdf_query_results *query_results,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *uri);
    void                librdf_free_query_results_formatter (librdf_query_results_formatter *formatter);
    int                 librdf_query_results_formats_check  (librdf_world *world,
                                                             const char *name,
                                                             librdf_uri *uri,
                                                             const char *mime_type);
    const raptor_syntax_description * librdf_query_results_formats_get_description
                                                            (librdf_world *world,
                                                             unsigned int counter);
    int                 librdf_query_results_formats_enumerate
                                                            (librdf_world *world,
                                                             const unsigned int counter,
                                                             const char **name,
                                                             const char **label,
                                                             const unsigned char **uri_string,
                                                             const char **mime_type);
    typedef             librdf_query_results_formatter;
    int                 librdf_query_results_formatter_write
                                                            (raptor_iostream *iostr,
                                                             librdf_query_results_formatter *formatter,
                                                             librdf_query_results *query_results,
                                                             librdf_uri *base_uri);

## Description

The results of an librdf_query execution as a sequence of individual results, an RDF graph as a sequence of triples or a boolean. For variable binding results, the binding names and values can be read in multiple forms and the number of results returned as well as the current result moved to the next. For an RDF graph result, the stream of triples can be returned. For a boolean result, the value can be returned. All results can be turned into a string XML format based on the SPARQL XML results format which can also be written to a file.

## Details

### librdf_query_results

    typedef struct librdf_query_results_s librdf_query_results;

Redland query results class.

### librdf_query_results_as_stream ()

    librdf_stream *     librdf_query_results_as_stream      (librdf_query_results *query_results);

Get a query result as an RDF graph in librdf_stream form

The return value is only meaningful if this is an RDF graph query result - see `librdf_query_results_is_graph()`.

`query_results` : | librdf_query_results query_results
Returns : | a new librdf_stream result or NULL on error

### librdf_query_results_get_count ()

    int                 librdf_query_results_get_count      (librdf_query_results *query_results);

Get number of bindings so far.

`query_results` : | librdf_query_results query results
Returns : | number of bindings found so far

### librdf_query_results_next ()

    int                 librdf_query_results_next           (librdf_query_results *query_results);

Move to the next result.

`query_results` : | librdf_query_results query results
Returns : | non-0 if failed or results exhausted

### librdf_query_results_finished ()

    int                 librdf_query_results_finished       (librdf_query_results *query_results);

Find out if binding results are exhausted.

`query_results` : | librdf_query_results query results
Returns : | non-0 if results are finished or query failed

### librdf_query_results_get_bindings ()

    int                 librdf_query_results_get_bindings   (librdf_query_results *query_results,
                                                             const char ***names,
                                                             librdf_node **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 used as an array to store pointers to the librdf_node* of the results. These nodes must be freed by the caller. The size of the array is determined by the number of names of bindings, returned by librdf_query_results_get_bindings_count dynamically or will be known in advanced if hard-coded into the query string.

Example

const char **names=NULL; librdf_node* values[10];

if(librdf_query_results_get_bindings(results, &names, values)) ...

`query_results` : | librdf_query_results query results
`names` : | pointer to an array of binding names (or NULL)
`values` : | pointer to an array of binding value librdf_node (or NULL)
Returns : | non-0 if the assignment failed

### librdf_query_results_get_binding_value ()

    librdf_node *       librdf_query_results_get_binding_value
                                                            (librdf_query_results *query_results,
                                                             int offset);

Get one binding value for the current result.

`query_results` : | librdf_query_results query results
`offset` : | offset of binding name into array of known names
Returns : | a new librdf_node binding value or NULL on failure

### librdf_query_results_get_binding_name ()

    const char *        librdf_query_results_get_binding_name
                                                            (librdf_query_results *query_results,
                                                             int offset);

Get binding name for the current result.

`query_results` : | librdf_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

### librdf_query_results_get_binding_value_by_name ()

    librdf_node *       librdf_query_results_get_binding_value_by_name
                                                            (librdf_query_results *query_results,
                                                             const char *name);

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

`query_results` : | librdf_query_results query results
`name` : | variable name
Returns : | a new librdf_node binding value or NULL on failure

### librdf_query_results_get_bindings_count ()

    int                 librdf_query_results_get_bindings_count
                                                            (librdf_query_results *query_results);

Get the number of bound variables in the result.

`query_results` : | librdf_query_results query results
Returns : | <0 if failed or results exhausted

### librdf_query_results_to_counted_string ()

    unsigned char *     librdf_query_results_to_counted_string
                                                            (librdf_query_results *query_results,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri,
                                                             size_t *length_p);

Turn a query results into a string.

The default query results format will be used if `format_uri` is NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

The `base_uri` may be used for as the base URI the generated syntax, depending on the format.

The returned string must be freed by the caller using `librdf_free_memory()`.

`deprecated`: Use `librdf_query_results_to_counted_string2()` with extra name and mime-type args.

`query_results` : | librdf_query_results object
`format_uri` : | URI of syntax to format to (or NULL)
`base_uri` : | Base URI of output formatted syntax (or NULL)
`length_p` : | Pointer to where to store length of string (or NULL)
Returns : | new string value or NULL on failure

### librdf_query_results_to_counted_string2 ()

    unsigned char *     librdf_query_results_to_counted_string2
                                                            (librdf_query_results *query_results,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri,
                                                             size_t *length_p);

Turn a query results into a string.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if `name`, `mime_type` and `format_uri` are all NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

The `base_uri` may be used for as the base URI the generated syntax, depending on the format.

The returned string must be freed by the caller using `librdf_free_memory()`.

`query_results` : | librdf_query_results object
`name` : | name of syntax to format to
`mime_type` : | mime type of syntax to format to (or NULL)
`format_uri` : | URI of syntax to format to (or NULL)
`base_uri` : | Base URI of output formatted syntax (or NULL)
`length_p` : | Pointer to where to store length of string (or NULL)
Returns : | new string value or NULL on failure

### librdf_query_results_to_string ()

    unsigned char *     librdf_query_results_to_string      (librdf_query_results *query_results,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);

Turn a query results into a string.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if `format_uri` is NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

The `base_uri` may be used for as the base URI the generated syntax, depending on the format.

The returned string must be freed by the caller using `librdf_free_memory()`.

`Deprecated`: use `librdf_query_results_to_string2()` with extra name and mime_type args.

`query_results` : | librdf_query_results object
`format_uri` : | URI of syntax to format to
`base_uri` : | Base URI of output formatted syntax (or NULL)
Returns : | new string value or NULL on failure

### librdf_query_results_to_string2 ()

    unsigned char *     librdf_query_results_to_string2     (librdf_query_results *query_results,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);

Turn a query results into a string.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if `name`, `mime_type` and `format_uri` are all NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

The `base_uri` may be used for as the base URI the generated syntax, depending on the format.

The returned string must be freed by the caller using `librdf_free_memory()`.

`query_results` : | librdf_query_results object
`name` : | format name
`mime_type` : | format mime type (or NULL)
`format_uri` : | URI of syntax to format to (or NULL)
`base_uri` : | Base URI of output formatted syntax (or NULL)
Returns : | new string value or NULL on failure

### librdf_query_results_to_file_handle ()

    int                 librdf_query_results_to_file_handle (librdf_query_results *query_results,
                                                             FILE *handle,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);

Write a query results to a FILE*.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if `format_uri` is NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

The `base_uri` may be used for as the base URI the generated syntax, depending on the format.

`Deprecated`: use `librdf_query_results_to_file_handle()` with extra name and mime_type args.

`query_results` : | librdf_query_results object
`handle` : | file handle to write to
`format_uri` : | URI of syntax to format to
`base_uri` : | Base URI of output formatted syntax (or NULL)
Returns : | non 0 on failure

### librdf_query_results_to_file_handle2 ()

    int                 librdf_query_results_to_file_handle2
                                                            (librdf_query_results *query_results,
                                                             FILE *handle,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);

Write a query results to a FILE*.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if `name`, `mime_type` and `format_uri` are all NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

The `base_uri` may be used for as the base URI the generated syntax, depending on the format.

`query_results` : | librdf_query_results object
`handle` : | file handle to write to
`name` : | result format name (or NULL)
`mime_type` : | result mime type (or NULL)
`format_uri` : | URI of syntax to format to (or NULL)
`base_uri` : | Base URI of output formatted syntax
Returns : | non 0 on failure

### librdf_query_results_to_file ()

    int                 librdf_query_results_to_file        (librdf_query_results *query_results,
                                                             const char *name,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);

Write a query results to a file.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if `format_uri` is NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

The `base_uri` may be used for as the base URI the generated syntax, depending on the format.

`Deprecated`: use `librdf_query_results_to_file2()` with extra mime_type arg.

`query_results` : | librdf_query_results object
`name` : | filename to write to
`format_uri` : | URI of syntax to format to
`base_uri` : | Base URI of output formatted syntax (or NULL)
Returns : | non 0 on failure

### librdf_query_results_to_file2 ()

    int                 librdf_query_results_to_file2       (librdf_query_results *query_results,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *format_uri,
                                                             librdf_uri *base_uri);

Write a query results to a file.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if `name`, `mime_type` and `format_uri` are all NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

The `base_uri` may be used for as the base URI the generated syntax, depending on the format.

`query_results` : | librdf_query_results object
`name` : | filename to write to
`mime_type` : | mime type (or NULL)
`format_uri` : | URI of syntax to format to (or NULL)
`base_uri` : | Base URI of output formatted syntax (or NULL)
Returns : | non 0 on failure

### librdf_free_query_results ()

    void                librdf_free_query_results           (librdf_query_results *query_results);

Destructor - destroy a librdf_query_results object.

`query_results` : | librdf_query_results object

### librdf_query_results_is_bindings ()

    int                 librdf_query_results_is_bindings    (librdf_query_results *query_results);

Test if librdf_query_results is variable bindings format.

`query_results` : | librdf_query_results object
Returns : | non-0 if true

### librdf_query_results_is_boolean ()

    int                 librdf_query_results_is_boolean     (librdf_query_results *query_results);

Test if librdf_query_results is boolean format.

If this function returns true, the result can be retrieved by `librdf_query_results_get_boolean()`.

`query_results` : | librdf_query_results object
Returns : | non-0 if true

### librdf_query_results_is_graph ()

    int                 librdf_query_results_is_graph       (librdf_query_results *query_results);

Test if librdf_query_results is RDF graph format.

`query_results` : | librdf_query_results object
Returns : | non-0 if true

### librdf_query_results_is_syntax ()

    int                 librdf_query_results_is_syntax      (librdf_query_results *query_results);

Test if librdf_query_results is a syntax.

If this function returns true, the ONLY result available from this query is a syntax that can be serialized using one of the query_result_formatter class methods or with `librdf_query_results_to_counted_string()`, `librdf_query_results_to_string()`, `librdf_query_results_to_file_handle()` or `librdf_query_results_to_file()`

`query_results` : | librdf_query_results object
Returns : | non-0 if true

### librdf_query_results_get_boolean ()

    int                 librdf_query_results_get_boolean    (librdf_query_results *query_results);

Get boolean query result.

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

`query_results` : | librdf_query_results query_results
Returns : | boolean query result - >0 is true, 0 is false, <0 on error or finished

### librdf_new_query_results_formatter ()

    librdf_query_results_formatter * librdf_new_query_results_formatter
                                                            (librdf_query_results *query_results,
                                                             const char *name,
                                                             librdf_uri *uri);

Constructor - create a new librdf_query_results_formatter object by identified format.

A query results format can be named or identified by a URI, both of which are optional. The default query results format will be used if `name` and `uri` are both NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

`Deprecated`: for `librdf_new_query_results_formatter2()` with the name, mime_type and format_uri args.

`query_results` : | librdf_query_results query_results
`name` : | the query results format name (or NULL)
`uri` : | librdf_uri query results format uri (or NULL)
Returns : | a new librdf_query_results_formatter object or NULL on failure

### librdf_new_query_results_formatter_by_mime_type ()

    librdf_query_results_formatter * librdf_new_query_results_formatter_by_mime_type
                                                            (librdf_query_results *query_results,
                                                             const char *mime_type);

Constructor - create a new librdf_query_results_formatter object by mime type.

A query results format generates a syntax with a mime type which may be requested with this constructor.

Note that there may be several formatters that generate the same MIME Type (such as SPARQL XML results format drafts) and in thot case the `librdf_new_query_results_formatter()` constructor allows selecting of a specific one by name or URI.

`Deprecated`: for `librdf_new_query_results_formatter2()` with the name, mime_type and format_uri args.

`query_results` : | librdf_query_results query_results
`mime_type` : | mime type name
Returns : | a new librdf_query_results_formatter object or NULL on failure

### librdf_new_query_results_formatter2 ()

    librdf_query_results_formatter * librdf_new_query_results_formatter2
                                                            (librdf_query_results *query_results,
                                                             const char *name,
                                                             const char *mime_type,
                                                             librdf_uri *uri);

Constructor - create a new librdf_query_results_formatter object by identified format.

A query results format can be named, have a mime type, or identified by a URI, all of which are optional. The default query results format will be used if `name`, `mime_type` and `uri` are all NULL.

`librdf_query_results_formats_enumerate()` returns information on the known query results names, labels and URIs.

`query_results` : | librdf_query_results query_results
`name` : | the query results format name (or NULL)
`mime_type` : | the query results format mime type (or NULL)
`uri` : | librdf_uri query results format uri (or NULL)
Returns : | a new librdf_query_results_formatter object or NULL on failure

### librdf_free_query_results_formatter ()

    void                librdf_free_query_results_formatter (librdf_query_results_formatter *formatter);

Destructor - destroy a librdf_query_results_formatter object.

`formatter` : | librdf_query_results_formatter object

### librdf_query_results_formats_check ()

    int                 librdf_query_results_formats_check  (librdf_world *world,
                                                             const char *name,
                                                             librdf_uri *uri,
                                                             const char *mime_type);

Check if a query results formatter exists for the requested format.

`world` : | librdf_world
`name` : | the query results format name (or NULL)
`uri` : | librdf_uri query results format uri (or NULL)
`mime_type` : | mime type name
Returns : | non-0 if a formatter exists.

### librdf_query_results_formats_get_description ()

    const raptor_syntax_description * librdf_query_results_formats_get_description
                                                            (librdf_world *world,
                                                             unsigned int counter);

Get query result formats descriptive syntax information

`world` : | world object
`counter` : | index into the list of query results formats
Returns : | description or NULL if counter is out of range

### librdf_query_results_formats_enumerate ()

    int                 librdf_query_results_formats_enumerate
                                                            (librdf_world *world,
                                                             const unsigned int counter,
                                                             const char **name,
                                                             const char **label,
                                                             const unsigned char **uri_string,
                                                             const char **mime_type);

Get information on query result syntaxes.

All returned strings are shared and must be copied if needed to be used dynamically.

`Deprecated`: use `librdf_query_results_formats_get_description()` to return more information in a static structure.

`world` : | librdf_world
`counter` : | index into the list of query result syntaxes
`name` : | pointer to store the name of the query result syntax (or NULL)
`label` : | pointer to store query result syntax readable label (or NULL)
`uri_string` : | pointer to store query result syntax URI string (or NULL)
`mime_type` : | pointer to store query result syntax mime type string (or NULL)
Returns : | non 0 on failure of if counter is out of range

### librdf_query_results_formatter

    typedef struct librdf_query_results_formatter_s librdf_query_results_formatter;

Redland query results formatter class.

### librdf_query_results_formatter_write ()

    int                 librdf_query_results_formatter_write
                                                            (raptor_iostream *iostr,
                                                             librdf_query_results_formatter *formatter,
                                                             librdf_query_results *query_results,
                                                             librdf_uri *base_uri);

Write the query results using the given formatter to an iostream

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

See `librdf_query_results_formats_enumerate()` to get the list of syntax URIs and their description.

`iostr` : | raptor_iostream to write the query to
`formatter` : | librdf_query_results_formatter object
`query_results` : | librdf_query_results query results format
`base_uri` : | librdf_uri base URI of the output format
Returns : | non-0 on failure