## Triple stores Triple stores — RDF Triple stores |

## Synopsis

    #define             LIBRDF_STORAGE_INTERFACE_VERSION
    #define             LIBRDF_STORAGE_MAX_INTERFACE_VERSION
    #define             LIBRDF_STORAGE_MIN_INTERFACE_VERSION
    typedef             librdf_storage;
    typedef             librdf_storage_factory;
    int                 librdf_storage_register_factory     (librdf_world *world,
                                                             const char *name,
                                                             const char *label,
                                                             void (*factory) (librdf_storage_factory*));
    int                 librdf_storage_enumerate            (librdf_world *world,
                                                             const unsigned int counter,
                                                             const char **name,
                                                             const char **label);
    librdf_storage *    librdf_new_storage                  (librdf_world *world,
                                                             const char *storage_name,
                                                             const char *name,
                                                             const char *options_string);
    librdf_storage *    librdf_new_storage_with_options     (librdf_world *world,
                                                             const char *storage_name,
                                                             const char *name,
                                                             librdf_hash *options);
    librdf_storage *    librdf_new_storage_from_storage     (librdf_storage *old_storage);
    librdf_storage *    librdf_new_storage_from_factory     (librdf_world *world,
                                                             librdf_storage_factory *factory,
                                                             const char *name,
                                                             librdf_hash *options);
    void                librdf_free_storage                 (librdf_storage *storage);
    int                 librdf_storage_open                 (librdf_storage *storage,
                                                             librdf_model *model);
    int                 librdf_storage_close                (librdf_storage *storage);
    int                 librdf_storage_size                 (librdf_storage *storage);
    int                 librdf_storage_add_statement        (librdf_storage *storage,
                                                             librdf_statement *statement);
    int                 librdf_storage_add_statements       (librdf_storage *storage,
                                                             librdf_stream *statement_stream);
    int                 librdf_storage_remove_statement     (librdf_storage *storage,
                                                             librdf_statement *statement);
    int                 librdf_storage_contains_statement   (librdf_storage *storage,
                                                             librdf_statement *statement);
    librdf_stream *     librdf_storage_serialise            (librdf_storage *storage);
    librdf_stream *     librdf_storage_find_statements      (librdf_storage *storage,
                                                             librdf_statement *statement);
    librdf_stream *     librdf_storage_find_statements_with_options
                                                            (librdf_storage *storage,
                                                             librdf_statement *statement,
                                                             librdf_node *context_node,
                                                             librdf_hash *options);
    librdf_iterator *   librdf_storage_get_sources          (librdf_storage *storage,
                                                             librdf_node *arc,
                                                             librdf_node *target);
    librdf_iterator *   librdf_storage_get_arcs             (librdf_storage *storage,
                                                             librdf_node *source,
                                                             librdf_node *target);
    librdf_iterator *   librdf_storage_get_targets          (librdf_storage *storage,
                                                             librdf_node *source,
                                                             librdf_node *arc);
    librdf_iterator *   librdf_storage_get_arcs_in          (librdf_storage *storage,
                                                             librdf_node *node);
    librdf_iterator *   librdf_storage_get_arcs_out         (librdf_storage *storage,
                                                             librdf_node *node);
    int                 librdf_storage_has_arc_in           (librdf_storage *storage,
                                                             librdf_node *node,
                                                             librdf_node *property);
    int                 librdf_storage_has_arc_out          (librdf_storage *storage,
                                                             librdf_node *node,
                                                             librdf_node *property);
    int                 librdf_storage_context_add_statement
                                                            (librdf_storage *storage,
                                                             librdf_node *context,
                                                             librdf_statement *statement);
    int                 librdf_storage_context_add_statements
                                                            (librdf_storage *storage,
                                                             librdf_node *context,
                                                             librdf_stream *stream);
    int                 librdf_storage_context_remove_statement
                                                            (librdf_storage *storage,
                                                             librdf_node *context,
                                                             librdf_statement *statement);
    int                 librdf_storage_context_remove_statements
                                                            (librdf_storage *storage,
                                                             librdf_node *context);
    librdf_stream *     librdf_storage_context_as_stream    (librdf_storage *storage,
                                                             librdf_node *context);
    librdf_stream *     librdf_storage_context_serialise    (librdf_storage *storage,
                                                             librdf_node *context);
    int                 librdf_storage_supports_query       (librdf_storage *storage,
                                                             librdf_query *query);
    librdf_query_results * librdf_storage_query_execute     (librdf_storage *storage,
                                                             librdf_query *query);
    int                 librdf_storage_sync                 (librdf_storage *storage);
    librdf_stream *     librdf_storage_find_statements_in_context
                                                            (librdf_storage *storage,
                                                             librdf_statement *statement,
                                                             librdf_node *context_node);
    librdf_iterator *   librdf_storage_get_contexts         (librdf_storage *storage);
    librdf_node *       librdf_storage_get_feature          (librdf_storage *storage,
                                                             librdf_uri *feature);
    int                 librdf_storage_set_feature          (librdf_storage *storage,
                                                             librdf_uri *feature,
                                                             librdf_node *value);
    int                 librdf_storage_transaction_commit   (librdf_storage *storage);
    void *              librdf_storage_transaction_get_handle
                                                            (librdf_storage *storage);
    int                 librdf_storage_transaction_rollback (librdf_storage *storage);
    int                 librdf_storage_transaction_start    (librdf_storage *storage);
    int                 librdf_storage_transaction_start_with_handle
                                                            (librdf_storage *storage,
                                                             void *handle);
    void                librdf_storage_add_reference        (librdf_storage *storage);
    void                librdf_storage_remove_reference     (librdf_storage *storage);
    typedef             librdf_storage_instance;
    librdf_storage_instance librdf_storage_get_instance     (librdf_storage *storage);
    void                librdf_storage_set_instance         (librdf_storage *storage,
                                                             librdf_storage_instance instance);
    librdf_world *      librdf_storage_get_world            (librdf_storage *storage);
    void                (*librdf_storage_module_register_function)
                                                            (librdf_world *world);

## Description

Provides classes to create triple stores to back the RDF graph interface (librdf_model). Most of the methods are for implementing the RDF model API and have the same name.

## Details

### LIBRDF_STORAGE_INTERFACE_VERSION

    #define LIBRDF_STORAGE_INTERFACE_VERSION LIBRDF_STORAGE_MAX_INTERFACE_VERSION

Default librdf storage module interface version.

### LIBRDF_STORAGE_MAX_INTERFACE_VERSION

    #define LIBRDF_STORAGE_MAX_INTERFACE_VERSION 1

Newest supported librdf storage module interface version.

### LIBRDF_STORAGE_MIN_INTERFACE_VERSION

    #define LIBRDF_STORAGE_MIN_INTERFACE_VERSION 1

Oldest support librdf storage module interface version.

### librdf_storage

    typedef struct librdf_storage_s librdf_storage;

Redland storage class.

### librdf_storage_factory

    typedef struct librdf_storage_factory_s librdf_storage_factory;

Redland storage factory class.

### librdf_storage_register_factory ()

    int                 librdf_storage_register_factory     (librdf_world *world,
                                                             const char *name,
                                                             const char *label,
                                                             void (*factory) (librdf_storage_factory*));

Register a storage factory.

Registration will fail if any of the parameters or NULL, if the factory API version is out of the known range or if out of memory.

`world` : | redland world object
`name` : | the storage factory name
`label` : | the storage factory label
`factory` : | pointer to function to call to register the factory
Returns : | non-0 on failure

### librdf_storage_enumerate ()

    int                 librdf_storage_enumerate            (librdf_world *world,
                                                             const unsigned int counter,
                                                             const char **name,
                                                             const char **label);

Get information on storages.

`world` : | redland world object
`counter` : | index into the list of storages
`name` : | pointer to store the name of the storage (or NULL)
`label` : | pointer to store syntax readable label (or NULL)
Returns : | non 0 on failure of if counter is out of range

### librdf_new_storage ()

    librdf_storage *    librdf_new_storage                  (librdf_world *world,
                                                             const char *storage_name,
                                                             const char *name,
                                                             const char *options_string);

Constructor - create a new librdf_storage object.

The options are encoded as described in `librdf_hash_from_string()` and can be NULL if none are required.

`world` : | redland world object
`storage_name` : | the storage factory name
`name` : | an identifier for the storage
`options_string` : | options to initialise storage
Returns : | a new librdf_storage object or NULL on failure

### librdf_new_storage_with_options ()

    librdf_storage *    librdf_new_storage_with_options     (librdf_world *world,
                                                             const char *storage_name,
                                                             const char *name,
                                                             librdf_hash *options);

Constructor - create a new librdf_storage object.

The options can be NULL if none are required.

`world` : | redland world object
`storage_name` : | the storage factory name
`name` : | an identifier for the storage
`options` : | librdf_hash of options to use
Returns : | a new librdf_storage object or NULL on failure

### librdf_new_storage_from_storage ()

    librdf_storage *    librdf_new_storage_from_storage     (librdf_storage *old_storage);

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

Should create a new storage in the same context as the existing one as appropriate for the storage. For example, in a RDBMS storage it would be a new database, or in on disk it would be a new set of files. This will mean automatically generating a new identifier for the storage, maybe based on the existing storage identifier.

`old_storage` : | the existing storage librdf_storage to use
Returns : | a new librdf_storage object or NULL on failure

### librdf_new_storage_from_factory ()

    librdf_storage *    librdf_new_storage_from_factory     (librdf_world *world,
                                                             librdf_storage_factory *factory,
                                                             const char *name,
                                                             librdf_hash *options);

Constructor - create a new librdf_storage object.

If the options are present, they become owned by the storage and should no longer be used.

`world` : | redland world object
`factory` : | the factory to use to construct the storage
`name` : | name to use for storage
`options` : | librdf_hash of options to initialise storage
Returns : | a new librdf_storage object or NULL on failure

### librdf_free_storage ()

    void                librdf_free_storage                 (librdf_storage *storage);

Destructor - destroy a librdf_storage object.

`storage` : | librdf_storage object

### librdf_storage_open ()

    int                 librdf_storage_open                 (librdf_storage *storage,
                                                             librdf_model *model);

Start a model / storage association.

This is ended with `librdf_storage_close()`

`storage` : | librdf_storage object
`model` : | model stored
Returns : | non 0 on failure

### librdf_storage_close ()

    int                 librdf_storage_close                (librdf_storage *storage);

End a model / storage association.

`storage` : | librdf_storage object
Returns : | non 0 on failure

### librdf_storage_size ()

    int                 librdf_storage_size                 (librdf_storage *storage);

Get the number of statements stored.

`storage` : | librdf_storage object
Returns : | The number of statements or < 0 if cannot be determined

### librdf_storage_add_statement ()

    int                 librdf_storage_add_statement        (librdf_storage *storage,
                                                             librdf_statement *statement);

Add a statement to a storage.

The passed-in statement is copied when added to the store, not shared with the store.

If the statement already exists in the store, it is not added unless Redland contexts are being used.

Enforces that the statement is legal for RDF - URI or blank subject, URI predicate and URI or blank or literal object (i.e. anything).

`storage` : | librdf_storage object
`statement` : | librdf_statement statement to add
Returns : | non 0 on failure, <0 on error, >0 if statement was illegal

### librdf_storage_add_statements ()

    int                 librdf_storage_add_statements       (librdf_storage *storage,
                                                             librdf_stream *statement_stream);

Add a stream of statements to the storage.

If any of the statements already exists in the store, they are not added unless Redland contexts are being used.

`storage` : | librdf_storage object
`statement_stream` : | librdf_stream of statements
Returns : | non 0 on failure

### librdf_storage_remove_statement ()

    int                 librdf_storage_remove_statement     (librdf_storage *storage,
                                                             librdf_statement *statement);

Remove a statement from the storage.

`storage` : | librdf_storage object
`statement` : | librdf_statement statement to remove
Returns : | non 0 on failure

### librdf_storage_contains_statement ()

    int                 librdf_storage_contains_statement   (librdf_storage *storage,
                                                             librdf_statement *statement);

Test if a given statement is present in the storage.

`storage` : | librdf_storage object
`statement` : | librdf_statement statement to check
Returns : | non 0 if the storage contains the statement (>0 if illegal statement)

### librdf_storage_serialise ()

    librdf_stream *     librdf_storage_serialise            (librdf_storage *storage);

Serialise the storage as a librdf_stream of statemetns.

`storage` : | librdf_storage object
Returns : | librdf_stream of statements or NULL on failure

### librdf_storage_find_statements ()

    librdf_stream *     librdf_storage_find_statements      (librdf_storage *storage,
                                                             librdf_statement *statement);

Search the storage for matching statements.

Searches the storage for a (partial) statement as described in `librdf_statement_match()` and returns a librdf_stream of matching librdf_statement objects.

`storage` : | librdf_storage object
`statement` : | librdf_statement partial statement to find
Returns : | librdf_stream of matching statements (may be empty) or NULL on failure

### librdf_storage_find_statements_with_options ()

    librdf_stream *     librdf_storage_find_statements_with_options
                                                            (librdf_storage *storage,
                                                             librdf_statement *statement,
                                                             librdf_node *context_node,
                                                             librdf_hash *options);

Search the storage for matching statements with match options.

Searches the storage for a (partial) statement as described in `librdf_statement_match()` and returns a librdf_stream of matching librdf_statement objects.

If options is given then the match is made according to the given options. If options is NULL, this is equivalent to librdf_storage_find_statements_in_context.

`storage` : | librdf_storage object
`statement` : | librdf_statement partial statement to find
`context_node` : | librdf_node context node or NULL.
`options` : | librdf_hash of matching options or NULL
Returns : | librdf_stream of matching statements (may be empty) or NULL on failure

### librdf_storage_get_sources ()

    librdf_iterator *   librdf_storage_get_sources          (librdf_storage *storage,
                                                             librdf_node *arc,
                                                             librdf_node *target);

Return the sources (subjects) of arc in an RDF graph given arc (predicate) and target (object).

Searches the storage for arcs matching the given arc and target and returns a list of the source librdf_node objects as an iterator

`storage` : | librdf_storage object
`arc` : | librdf_node arc
`target` : | librdf_node target
Returns : | librdf_iterator of librdf_node objects (may be empty) or NULL on failure

### librdf_storage_get_arcs ()

    librdf_iterator *   librdf_storage_get_arcs             (librdf_storage *storage,
                                                             librdf_node *source,
                                                             librdf_node *target);

Return the arcs (predicates) of an arc in an RDF graph given source (subject) and target (object).

Searches the storage for arcs matching the given source and target and returns a list of the arc librdf_node objects as an iterator

`storage` : | librdf_storage object
`source` : | librdf_node source
`target` : | librdf_node target
Returns : | librdf_iterator of librdf_node objects (may be empty) or NULL on failure

### librdf_storage_get_targets ()

    librdf_iterator *   librdf_storage_get_targets          (librdf_storage *storage,
                                                             librdf_node *source,
                                                             librdf_node *arc);

Return the targets (objects) of an arc in an RDF graph given source (subject) and arc (predicate).

Searches the storage for targets matching the given source and arc and returns a list of the source librdf_node objects as an iterator

`storage` : | librdf_storage object
`source` : | librdf_node source
`arc` : | librdf_node arc
Returns : | librdf_iterator of librdf_node objects (may be empty) or NULL on failure

### librdf_storage_get_arcs_in ()

    librdf_iterator *   librdf_storage_get_arcs_in          (librdf_storage *storage,
                                                             librdf_node *node);

Return the properties pointing to the given resource.

`storage` : | librdf_storage object
`node` : | librdf_node resource node
Returns : | librdf_iterator of librdf_node objects (may be empty) or NULL on failure

### librdf_storage_get_arcs_out ()

    librdf_iterator *   librdf_storage_get_arcs_out         (librdf_storage *storage,
                                                             librdf_node *node);

Return the properties pointing from the given resource.

`storage` : | librdf_storage object
`node` : | librdf_node resource node
Returns : | librdf_iterator of librdf_node objects (may be empty) or NULL on failure

### librdf_storage_has_arc_in ()

    int                 librdf_storage_has_arc_in           (librdf_storage *storage,
                                                             librdf_node *node,
                                                             librdf_node *property);

Check if a node has a given property pointing to it.

`storage` : | librdf_storage object
`node` : | librdf_node resource node
`property` : | librdf_node property node
Returns : | non 0 if arc property does point to the resource node

### librdf_storage_has_arc_out ()

    int                 librdf_storage_has_arc_out          (librdf_storage *storage,
                                                             librdf_node *node,
                                                             librdf_node *property);

Check if a node has a given property pointing from it.

`storage` : | librdf_storage object
`node` : | librdf_node resource node
`property` : | librdf_node property node
Returns : | non 0 if arc property does point from the resource node

### librdf_storage_context_add_statement ()

    int                 librdf_storage_context_add_statement
                                                            (librdf_storage *storage,
                                                             librdf_node *context,
                                                             librdf_statement *statement);

Add a statement to a storage in a context.

If `context` is NULL, this is equivalent to librdf_storage_add_statement

`storage` : | librdf_storage object
`context` : | librdf_node context node
`statement` : | librdf_statement statement to add
Returns : | non 0 on failure

### librdf_storage_context_add_statements ()

    int                 librdf_storage_context_add_statements
                                                            (librdf_storage *storage,
                                                             librdf_node *context,
                                                             librdf_stream *stream);

Add statements to a storage with a context.

If `context` is NULL, this is equivalent to librdf_storage_add_statements

`storage` : | librdf_storage object
`context` : | librdf_node context
`stream` : | librdf_stream stream object
Returns : | Non 0 on failure

### librdf_storage_context_remove_statement ()

    int                 librdf_storage_context_remove_statement
                                                            (librdf_storage *storage,
                                                             librdf_node *context,
                                                             librdf_statement *statement);

Remove a statement from a storage in a context.

If `context` is NULL, this is equivalent to librdf_storage_remove_statement

`storage` : | librdf_storage object
`context` : | librdf_node context node
`statement` : | librdf_statement statement to remove
Returns : | non 0 on failure

### librdf_storage_context_remove_statements ()

    int                 librdf_storage_context_remove_statements
                                                            (librdf_storage *storage,
                                                             librdf_node *context);

Remove statements from a storage with the given context.

`storage` : | librdf_storage object
`context` : | librdf_uri context
Returns : | Non 0 on failure

### librdf_storage_context_as_stream ()

    librdf_stream *     librdf_storage_context_as_stream    (librdf_storage *storage,
                                                             librdf_node *context);

List all statements in a storage context.

`storage` : | librdf_storage object
`context` : | librdf_node context node
Returns : | librdf_stream of statements or NULL on failure or context is empty

### librdf_storage_context_serialise ()

    librdf_stream *     librdf_storage_context_serialise    (librdf_storage *storage,
                                                             librdf_node *context);

List all statements in a storage context (DEPRECATED).

DEPRECATED to reduce confusion with the librdf_serializer class. Please use librdf_storage_context_as_stream.

`storage` : | librdf_storage object
`context` : | librdf_node context node
Returns : | librdf_stream of statements or NULL on failure or context is empty

### librdf_storage_supports_query ()

    int                 librdf_storage_supports_query       (librdf_storage *storage,
                                                             librdf_query *query);

Check if a storage system supports a query language.

`storage` : | librdf_storage object
`query` : | librdf_query query object
Returns : | non-0 if the query is supported.

### librdf_storage_query_execute ()

    librdf_query_results * librdf_storage_query_execute     (librdf_storage *storage,
                                                             librdf_query *query);

Run the given query against the storage.

`storage` : | librdf_storage object
`query` : | librdf_query query object
Returns : | librdf_query_results or NULL on failure

### librdf_storage_sync ()

    int                 librdf_storage_sync                 (librdf_storage *storage);

Synchronise the storage to the storage implementation.

`storage` : | librdf_storage object
Returns : | non-0 on failure

### librdf_storage_find_statements_in_context ()

    librdf_stream *     librdf_storage_find_statements_in_context
                                                            (librdf_storage *storage,
                                                             librdf_statement *statement,
                                                             librdf_node *context_node);

Search the storage for matching statements in a given context.

Searches the storage for a (partial) statement as described in `librdf_statement_match()` in the given context and returns a librdf_stream of matching librdf_statement objects. If context is NULL, this is equivalent to librdf_storage_find_statements.

`storage` : | librdf_storage object
`statement` : | librdf_statement partial statement to find
`context_node` : | context librdf_node (or NULL)
Returns : | librdf_stream of matching statements (may be empty) or NULL on failure

### librdf_storage_get_contexts ()

    librdf_iterator *   librdf_storage_get_contexts         (librdf_storage *storage);

Return the list of contexts in the store.

Returns an iterator of librdf_node context nodes for each context in the store.

`storage` : | librdf_storage object
Returns : | librdf_iterator of context nodes or NULL on failure or if contexts are not supported

### librdf_storage_get_feature ()

    librdf_node *       librdf_storage_get_feature          (librdf_storage *storage,
                                                             librdf_uri *feature);

Get the value of a storage feature.

`storage` : | librdf_storage object
`feature` : | librdf_uri feature property
Returns : | new librdf_node feature value or NULL if no such feature exists or the value is empty.

### librdf_storage_set_feature ()

    int                 librdf_storage_set_feature          (librdf_storage *storage,
                                                             librdf_uri *feature,
                                                             librdf_node *value);

Set the value of a storage feature.

`storage` : | librdf_storage object
`feature` : | librdf_uri feature property
`value` : | librdf_node feature property value
Returns : | non 0 on failure (negative if no such feature)

### librdf_storage_transaction_commit ()

    int                 librdf_storage_transaction_commit   (librdf_storage *storage);

Commit a transaction.

`storage` : | the storage object
Returns : | non-0 on failure

### librdf_storage_transaction_get_handle ()

    void *              librdf_storage_transaction_get_handle
                                                            (librdf_storage *storage);

Get the current transaction handle.

`storage` : | the storage object
Returns : | non-0 on failure

### librdf_storage_transaction_rollback ()

    int                 librdf_storage_transaction_rollback (librdf_storage *storage);

Rollback a transaction.

`storage` : | the storage object
Returns : | non-0 on failure

### librdf_storage_transaction_start ()

    int                 librdf_storage_transaction_start    (librdf_storage *storage);

Start a transaction

`storage` : | the storage object
Returns : | non-0 on failure

### librdf_storage_transaction_start_with_handle ()

    int                 librdf_storage_transaction_start_with_handle
                                                            (librdf_storage *storage,
                                                             void *handle);

Start a transaction using an existing external transaction object.

`storage` : | the storage object
`handle` : | the transaction object
Returns : | non-0 on failure

### librdf_storage_add_reference ()

    void                librdf_storage_add_reference        (librdf_storage *storage);

Increment storage reference count by one.

This function is intended to be internal to librdf storage modules.

`storage` : | librdf_storage object

### librdf_storage_remove_reference ()

    void                librdf_storage_remove_reference     (librdf_storage *storage);

Decrement storage reference count by one and free the storage if reference count becomes zero.

This function is intended to be internal to librdf storage modules.

`storage` : | librdf_storage object

### librdf_storage_instance

    typedef void* librdf_storage_instance;

Opaque storage module instance handle.

For use with a storage module and the `librdf_storage_get_instance()` and `librdf_storage_set_instance()` functions. The instance handle should be set in the librdf_storage_factory init factory method.

### librdf_storage_get_instance ()

    librdf_storage_instance librdf_storage_get_instance     (librdf_storage *storage);

Get instance data for this storage

`storage` : | librdf_storage object
Returns : | opaque instance data for this storage

### librdf_storage_set_instance ()

    void                librdf_storage_set_instance         (librdf_storage *storage,
                                                             librdf_storage_instance instance);

Set the instance data for this storage.

This function is intended for use by the 'init' method of storage implementations to set instance data which can be retrived with `librdf_storage_get_instance()` and used in other methods of that storage.

The instance is completely opaque to librdf, including allocation and deallocation.

`storage` : | librdf_storage object
`instance` : | Opaque instance pointer

### librdf_storage_get_world ()

    librdf_world *      librdf_storage_get_world            (librdf_storage *storage);

Get the librdf_world object associated with this storage.

`storage` : | librdf_storage object
Returns : | world object for this storage

### librdf_storage_module_register_function ()

    void                (*librdf_storage_module_register_function)
                                                            (librdf_world *world);

Registration function for storage

A storage module must define and export a function named of this type with function name "librdf_storage_module_register_factory".

This function will be called by Redland and must call `librdf_storage_register_factory()` to register whatever storage backends are implemented in the module.

`world` : | world object