## section-query_results

section-query_results

## Functions

rasqal_query_results * | rasqal_new_query_results ()
rasqal_query_results * | rasqal_new_query_results2 ()
rasqal_query_results * | rasqal_new_query_results_from_string ()
void | rasqal_free_query_results ()
int | rasqal_query_results_add_row ()
int | rasqal_query_results_finished ()
const unsigned char * | rasqal_query_results_get_binding_name ()
rasqal_literal * | rasqal_query_results_get_binding_value ()
rasqal_literal * | rasqal_query_results_get_binding_value_by_name ()
int | rasqal_query_results_get_bindings ()
int | rasqal_query_results_get_bindings_count ()
int | rasqal_query_results_get_boolean ()
int | rasqal_query_results_get_count ()
rasqal_query * | rasqal_query_results_get_query ()
raptor_statement * | rasqal_query_results_get_triple ()
rasqal_row * | rasqal_query_results_get_row_by_offset ()
rasqal_query_results_type | rasqal_query_results_get_type ()
int | rasqal_query_results_is_bindings ()
int | rasqal_query_results_is_boolean ()
int | rasqal_query_results_is_graph ()
int | rasqal_query_results_is_syntax ()
int | rasqal_query_results_next ()
int | rasqal_query_results_next_triple ()
int | rasqal_query_results_read ()
int | rasqal_query_results_write ()
const char * | rasqal_query_results_type_label ()
int | rasqal_query_results_rewind ()

## Types and Values

typedef | rasqal_query_results
enum | rasqal_query_results_type

## Description

## Functions

### 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);

`rasqal_new_query_results` is deprecated and should not be used in newly-written code.

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

#### Parameters

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

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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.

#### Parameters

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

### 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

#### Parameters

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.

#### Parameters

query_results | rasqal_query_results query_results |

#### Returns

non-0 if rewinding is not available when results are not stored

## Types and Values

### rasqal_query_results

    rasqal_graph_query_results* query_results;

Rasqal query results class.

### enum rasqal_query_results_type

Query result type.

#### Members

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 |