## Querying

Querying — RDF query languages and execution.

## Synopsis

    typedef             librdf_query;
    typedef             librdf_query_factory;
    void                librdf_query_register_factory       (librdf_world *world,
                                                             const char *name,
                                                             const unsigned char *uri_string,
                                                             void (*factory) (librdf_query_factory*));
    const raptor_syntax_description *  librdf_query_language_get_description
                                                            (librdf_world *world,
                                                             unsigned int counter);
    int                 librdf_query_languages_enumerate    (librdf_world *world,
                                                             const unsigned int counter,
                                                             const char **name,
                                                             const unsigned char **uri_string);
    librdf_query *      librdf_new_query                    (librdf_world *world,
                                                             const char *name,
                                                             librdf_uri *uri,
                                                             const unsigned char *query_string,
                                                             librdf_uri *base_uri);
    librdf_query *      librdf_new_query_from_query         (librdf_query *old_query);
    librdf_query *      librdf_new_query_from_factory       (librdf_world *world,
                                                             librdf_query_factory *factory,
                                                             const char *name,
                                                             librdf_uri *uri,
                                                             const unsigned char *query_string,
                                                             librdf_uri *base_uri);
    void                librdf_free_query                   (librdf_query *query);
    librdf_query_results *  librdf_query_execute            (librdf_query *query,
                                                             librdf_model *model);
    int                 librdf_query_get_limit              (librdf_query *query);
    int                 librdf_query_set_limit              (librdf_query *query,
                                                             int limit);
    int                 librdf_query_get_offset             (librdf_query *query);
    int                 librdf_query_set_offset             (librdf_query *query,
                                                             int offset);

## Description

Provides classes to create query objects and to execute them over an RDF graph (librdf_model) returning a librdf_query_results Query result limits and offsets can be set.

## Details

### librdf_query

    typedef struct librdf_query_s librdf_query;

Redland query class.

### librdf_query_factory

    typedef struct librdf_query_factory_s librdf_query_factory;

Redland query factory class.

### librdf_query_register_factory ()

    void                librdf_query_register_factory       (librdf_world *world,
                                                             const char *name,
                                                             const unsigned char *uri_string,
                                                             void (*factory) (librdf_query_factory*));

Register a query factory.

`world` : | redland world object
`name` : | the query language name
`uri_string` : | the query language URI string (or NULL if none)
`factory` : | pointer to function to call to register the factory

### librdf_query_language_get_description ()

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

Get a query language syntax description.

`world` : | librdf_world
`counter` : | index into the list of query language syntaxes
Returns : | description or NULL if counter is out of range

### librdf_query_languages_enumerate ()

    int                 librdf_query_languages_enumerate    (librdf_world *world,
                                                             const unsigned int counter,
                                                             const char **name,
                                                             const unsigned char **uri_string);

Get information on query language syntaxes.

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

`deprecated`: use `librdf_query_language_get_description()` to return more information in a static structure.

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

### librdf_new_query ()

    librdf_query *      librdf_new_query                    (librdf_world *world,
                                                             const char *name,
                                                             librdf_uri *uri,
                                                             const unsigned char *query_string,
                                                             librdf_uri *base_uri);

Constructor - create a new librdf_query object.

`world` : | redland world object
`name` : | the name identifying the query language
`uri` : | the URI identifying the query language (or NULL)
`query_string` : | the query string
`base_uri` : | the base URI of the query string (or NULL)
Returns : | a new librdf_query object or NULL on failure

### librdf_new_query_from_query ()

    librdf_query *      librdf_new_query_from_query         (librdf_query *old_query);

Copy constructor - create a new librdf_query object from an existing one

Should create a new query in the same context as the existing one as appropriate.

`old_query` : | the existing query librdf_query to use
Returns : | a new librdf_query object or NULL on failure

### librdf_new_query_from_factory ()

    librdf_query *      librdf_new_query_from_factory       (librdf_world *world,
                                                             librdf_query_factory *factory,
                                                             const char *name,
                                                             librdf_uri *uri,
                                                             const unsigned char *query_string,
                                                             librdf_uri *base_uri);

Constructor - create a new librdf_query object.

`world` : | redland world object
`factory` : | the factory to use to construct the query
`name` : | query language name
`uri` : | query language URI (or NULL)
`query_string` : | the query string
`base_uri` : | base URI of the query string (or NULL)
Returns : | a new librdf_query object or NULL on failure

### librdf_free_query ()

    void                librdf_free_query                   (librdf_query *query);

Destructor - destroy a librdf_query object.

`query` : | librdf_query object

### librdf_query_execute ()

    librdf_query_results *  librdf_query_execute            (librdf_query *query,
                                                             librdf_model *model);

Run the query on a model.

Runs the query against the (previously registered) model and returns a librdf_query_results for the result objects.

`query` : | librdf_query object
`model` : | model to operate query on
Returns : | librdf_query_results or NULL on failure

### librdf_query_get_limit ()

    int                 librdf_query_get_limit              (librdf_query *query);

Get the query-specified limit on results.

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

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

### librdf_query_set_limit ()

    int                 librdf_query_set_limit              (librdf_query *query,
                                                             int limit);

Set the query-specified limit on results.

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

`query` : | librdf_query query object
`limit` : | the limit on results, >=0 to set a limit, <0 to have no limit
Returns : | non-0 on failure

### librdf_query_get_offset ()

    int                 librdf_query_get_offset             (librdf_query *query);

Get the query-specified offset on results.

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

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

### librdf_query_set_offset ()

    int                 librdf_query_set_offset             (librdf_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` : | librdf_query query object
`offset` : | offset for results, >=0 to set an offset, <0 to have no offset
Returns : | non-0 on failure