Struct oxigraph::store::Store

pub struct Store { /* private fields */ }

An on-disk RDF dataset. Allows to query and update it using SPARQL. It is based on the RocksDB key-value store.

This store ensures the “repeatable read” isolation level: the store only exposes changes that have been “committed” (i.e. no partial writes) and the exposed state does not change for the complete duration of a read operation (e.g. a SPARQL query) or a read/write operation (e.g. a SPARQL update).

Usage example:

use oxigraph::store::Store;
use oxigraph::sparql::QueryResults;
use oxigraph::model::*;

let store = Store::open("example.db")?;

// insertion
let ex = NamedNode::new("http://example.com")?;
let quad = Quad::new(ex.clone(), ex.clone(), ex.clone(), GraphName::DefaultGraph);
store.insert(&quad)?;

// quad filter
let results: Result<Vec<Quad>,_> = store.quads_for_pattern(None, None, None, None).collect();
assert_eq!(vec![quad], results?);

// SPARQL query
if let QueryResults::Solutions(mut solutions) = store.query("SELECT ?s WHERE { ?s ?p ?o }")? {
    assert_eq!(solutions.next().unwrap()?.get("s"), Some(&ex.into()));
};

Implementations

impl Store

pub fn new() -> Result<Self, StorageError>

Creates a temporary Store that will be deleted after drop.

pub fn open(path: impl AsRef<Path>) -> Result<Self, StorageError>

Opens a read-write Store and creates it if it does not exist yet.

Only one read-write Store can exist at the same time. If you want to have extra Store instance opened on a same data use Store::open_secondary or Store::open_read_only.

pub fn open_secondary( primary_path: impl AsRef<Path> ) -> Result<Self, StorageError>

Opens a read-only clone of a running read-write Store.

Changes done while this process is running will be replicated after a possible lag.

It should only be used if a primary instance opened with Store::open is running at the same time. primary_path must be the path of the primary instance. This secondary instance will use temporary storage for the secondary instance cache. If you prefer persistent storage use Store::open_persistent_secondary.

If you want to simple read-only Store use Store::open_read_only.

pub fn open_persistent_secondary( primary_path: impl AsRef<Path>, secondary_path: impl AsRef<Path> ) -> Result<Self, StorageError>

Opens a read-only clone of a running read-write Store with persistence of the secondary instance cache.

Changes done while this process is running will be replicated after a possible lag.

It should only be used if a primary instance opened with Store::open is running at the same time. primary_path must be the path of the primary instance and secondary_path an other directory for the secondary instance cache.

If you want to simple read-only Store use Store::open_read_only.

pub fn open_read_only(path: impl AsRef<Path>) -> Result<Self, StorageError>

Opens a read-only Store from disk.

Opening as read-only while having an other process writing the database is undefined behavior. Store::open_secondary should be used in this case.

pub fn query( &self, query: impl TryInto<Query, Error = impl Into<EvaluationError>> ) -> Result<QueryResults, EvaluationError>

Executes a SPARQL 1.1 query.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;
use oxigraph::sparql::QueryResults;

let store = Store::new()?;

// insertions
let ex = NamedNodeRef::new("http://example.com")?;
store.insert(QuadRef::new(ex, ex, ex, GraphNameRef::DefaultGraph))?;

// SPARQL query
if let QueryResults::Solutions(mut solutions) =  store.query("SELECT ?s WHERE { ?s ?p ?o }")? {
    assert_eq!(solutions.next().unwrap()?.get("s"), Some(&ex.into_owned().into()));
}

pub fn query_opt( &self, query: impl TryInto<Query, Error = impl Into<EvaluationError>>, options: QueryOptions ) -> Result<QueryResults, EvaluationError>

Executes a SPARQL 1.1 query with some options.

Usage example with a custom function serializing terms to N-Triples:

use oxigraph::store::Store;
use oxigraph::model::*;
use oxigraph::sparql::{QueryOptions, QueryResults};

let store = Store::new()?;
if let QueryResults::Solutions(mut solutions) = store.query_opt(
    "SELECT (<http://www.w3.org/ns/formats/N-Triples>(1) AS ?nt) WHERE {}",
    QueryOptions::default().with_custom_function(
        NamedNode::new("http://www.w3.org/ns/formats/N-Triples")?,
        |args| args.get(0).map(|t| Literal::from(t.to_string()).into())
    )
)? {
    assert_eq!(solutions.next().unwrap()?.get("nt"), Some(&Literal::from("\"1\"^^<http://www.w3.org/2001/XMLSchema#integer>").into()));
}

pub fn explain_query_opt( &self, query: impl TryInto<Query, Error = impl Into<EvaluationError>>, options: QueryOptions, with_stats: bool ) -> Result<(Result<QueryResults, EvaluationError>, QueryExplanation), EvaluationError>

Executes a SPARQL 1.1 query with some options and returns a query explanation with some statistics (if enabled with the with_stats parameter).

Beware: if you want to compute statistics you need to exhaust the results iterator before having a look at them.

Usage example serialising the explanation with statistics in JSON:

use oxigraph::store::Store;
use oxigraph::sparql::{QueryOptions, QueryResults};

let store = Store::new()?;
if let (Ok(QueryResults::Solutions(solutions)), explanation) =  store.explain_query_opt("SELECT ?s WHERE { VALUES ?s { 1 2 3 } }", QueryOptions::default(), true)? {
    // We make sure to have read all the solutions
    for _ in solutions {
    }
    let mut buf = Vec::new();
    explanation.write_in_json(&mut buf)?;
}

pub fn quads_for_pattern( &self, subject: Option<SubjectRef<'_>>, predicate: Option<NamedNodeRef<'_>>, object: Option<TermRef<'_>>, graph_name: Option<GraphNameRef<'_>> ) -> QuadIter

Retrieves quads with a filter on each quad component

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let store = Store::new()?;

// insertion
let ex = NamedNode::new("http://example.com")?;
let quad = Quad::new(ex.clone(), ex.clone(), ex.clone(), GraphName::DefaultGraph);
store.insert(&quad)?;

// quad filter by object
let results = store.quads_for_pattern(None, None, Some((&ex).into()), None).collect::<Result<Vec<_>,_>>()?;
assert_eq!(vec![quad], results);

pub fn iter(&self) -> QuadIter

Returns all the quads contained in the store.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let store = Store::new()?;

// insertion
let ex = NamedNode::new("http://example.com")?;
let quad = Quad::new(ex.clone(), ex.clone(), ex.clone(), GraphName::DefaultGraph);
store.insert(&quad)?;

// quad filter by object
let results = store.iter().collect::<Result<Vec<_>,_>>()?;
assert_eq!(vec![quad], results);

pub fn contains<'a>( &self, quad: impl Into<QuadRef<'a>> ) -> Result<bool, StorageError>

Checks if this store contains a given quad.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let ex = NamedNodeRef::new("http://example.com")?;
let quad = QuadRef::new(ex, ex, ex, ex);

let store = Store::new()?;
assert!(!store.contains(quad)?);

store.insert(quad)?;
assert!(store.contains(quad)?);

pub fn len(&self) -> Result<usize, StorageError>

Returns the number of quads in the store.

Warning: this function executes a full scan.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let ex = NamedNodeRef::new("http://example.com")?;
let store = Store::new()?;
store.insert(QuadRef::new(ex, ex, ex, ex))?;
store.insert(QuadRef::new(ex, ex, ex, GraphNameRef::DefaultGraph))?;    
assert_eq!(2, store.len()?);

pub fn is_empty(&self) -> Result<bool, StorageError>

Returns if the store is empty.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let store = Store::new()?;
assert!(store.is_empty()?);

let ex = NamedNodeRef::new("http://example.com")?;
store.insert(QuadRef::new(ex, ex, ex, ex))?;
assert!(!store.is_empty()?);

pub fn transaction<'a, 'b: 'a, T, E: Error + 'static + From<StorageError>>( &'b self, f: impl Fn(Transaction<'a>) -> Result<T, E> ) -> Result<T, E>

Executes a transaction.

Transactions ensure the “repeatable read” isolation level: the store only exposes changes that have been “committed” (i.e. no partial writes) and the exposed state does not change for the complete duration of a read operation (e.g. a SPARQL query) or a read/write operation (e.g. a SPARQL update).

Usage example:

use oxigraph::store::{StorageError, Store};
use oxigraph::model::*;

let store = Store::new()?;
let a = NamedNodeRef::new("http://example.com/a")?;
let b = NamedNodeRef::new("http://example.com/b")?;

// Copy all triples about ex:a to triples about ex:b
store.transaction(|mut transaction| {
    for q in transaction.quads_for_pattern(Some(a.into()), None, None, None) {
        let q = q?;
        transaction.insert(QuadRef::new(b, &q.predicate, &q.object, &q.graph_name))?;
    }
    Result::<_, StorageError>::Ok(())
})?;

pub fn update( &self, update: impl TryInto<Update, Error = impl Into<EvaluationError>> ) -> Result<(), EvaluationError>

Executes a SPARQL 1.1 update.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let store = Store::new()?;

// insertion
store.update("INSERT DATA { <http://example.com> <http://example.com> <http://example.com> }")?;

// we inspect the store contents
let ex = NamedNodeRef::new("http://example.com")?;
assert!(store.contains(QuadRef::new(ex, ex, ex, GraphNameRef::DefaultGraph))?);

pub fn update_opt( &self, update: impl TryInto<Update, Error = impl Into<EvaluationError>>, options: impl Into<UpdateOptions> ) -> Result<(), EvaluationError>

Executes a SPARQL 1.1 update with some options.

use oxigraph::store::Store;
use oxigraph::model::*;
use oxigraph::sparql::QueryOptions;

let store = Store::new()?;
store.update_opt(
    "INSERT { ?s <http://example.com/n-triples-representation> ?n } WHERE { ?s ?p ?o BIND(<http://www.w3.org/ns/formats/N-Triples>(?s) AS ?nt) }",
    QueryOptions::default().with_custom_function(
        NamedNode::new("http://www.w3.org/ns/formats/N-Triples")?,
        |args| args.get(0).map(|t| Literal::from(t.to_string()).into())
    )
)?;

pub fn load_graph<'a>( &self, reader: impl BufRead, format: GraphFormat, to_graph_name: impl Into<GraphNameRef<'a>>, base_iri: Option<&str> ) -> Result<(), LoaderError>

Loads a graph file (i.e. triples) into the store.

This function is atomic, quite slow and memory hungry. To get much better performances you might want to use the bulk_loader.

Usage example:

use oxigraph::store::Store;
use oxigraph::io::GraphFormat;
use oxigraph::model::*;

let store = Store::new()?;

// insertion
let file = b"<http://example.com> <http://example.com> <http://example.com> .";
store.load_graph(file.as_ref(), GraphFormat::NTriples, GraphNameRef::DefaultGraph, None)?;

// we inspect the store contents
let ex = NamedNodeRef::new("http://example.com")?;
assert!(store.contains(QuadRef::new(ex, ex, ex, GraphNameRef::DefaultGraph))?);

pub fn load_dataset( &self, reader: impl BufRead, format: DatasetFormat, base_iri: Option<&str> ) -> Result<(), LoaderError>

Loads a dataset file (i.e. quads) into the store.

This function is atomic, quite slow and memory hungry. To get much better performances you might want to use the bulk_loader.

Usage example:

use oxigraph::store::Store;
use oxigraph::io::DatasetFormat;
use oxigraph::model::*;

let store = Store::new()?;

// insertion
let file = b"<http://example.com> <http://example.com> <http://example.com> <http://example.com> .";
store.load_dataset(file.as_ref(), DatasetFormat::NQuads, None)?;

// we inspect the store contents
let ex = NamedNodeRef::new("http://example.com")?;
assert!(store.contains(QuadRef::new(ex, ex, ex, ex))?);

pub fn insert<'a>( &self, quad: impl Into<QuadRef<'a>> ) -> Result<bool, StorageError>

Adds a quad to this store.

Returns true if the quad was not already in the store.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let ex = NamedNodeRef::new("http://example.com")?;
let quad = QuadRef::new(ex, ex, ex, GraphNameRef::DefaultGraph);

let store = Store::new()?;
assert!(store.insert(quad)?);
assert!(!store.insert(quad)?);

assert!(store.contains(quad)?);

pub fn extend( &self, quads: impl IntoIterator<Item = impl Into<Quad>> ) -> Result<(), StorageError>

Adds atomically a set of quads to this store.

Warning: This operation uses a memory heavy transaction internally, use the bulk_loader if you plan to add ten of millions of triples.

pub fn remove<'a>( &self, quad: impl Into<QuadRef<'a>> ) -> Result<bool, StorageError>

Removes a quad from this store.

Returns true if the quad was in the store and has been removed.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let ex = NamedNodeRef::new("http://example.com")?;
let quad = QuadRef::new(ex, ex, ex, GraphNameRef::DefaultGraph);

let store = Store::new()?;
store.insert(quad)?;
assert!(store.remove(quad)?);
assert!(!store.remove(quad)?);

assert!(!store.contains(quad)?);

pub fn dump_graph<'a>( &self, writer: impl Write, format: GraphFormat, from_graph_name: impl Into<GraphNameRef<'a>> ) -> Result<(), SerializerError>

Dumps a store graph into a file.

Usage example:

use oxigraph::store::Store;
use oxigraph::io::GraphFormat;
use oxigraph::model::GraphNameRef;

let file = "<http://example.com> <http://example.com> <http://example.com> .\n".as_bytes();

let store = Store::new()?;
store.load_graph(file, GraphFormat::NTriples, GraphNameRef::DefaultGraph, None)?;

let mut buffer = Vec::new();
store.dump_graph(&mut buffer, GraphFormat::NTriples, GraphNameRef::DefaultGraph)?;
assert_eq!(file, buffer.as_slice());

pub fn dump_dataset( &self, writer: impl Write, format: DatasetFormat ) -> Result<(), SerializerError>

Dumps the store into a file.

use oxigraph::store::Store;
use oxigraph::io::DatasetFormat;

let file = "<http://example.com> <http://example.com> <http://example.com> <http://example.com> .\n".as_bytes();

let store = Store::new()?;
store.load_dataset(file, DatasetFormat::NQuads, None)?;

let mut buffer = Vec::new();
store.dump_dataset(&mut buffer, DatasetFormat::NQuads)?;
assert_eq!(file, buffer.as_slice());

pub fn named_graphs(&self) -> GraphNameIter

Returns all the store named graphs.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let ex = NamedNode::new("http://example.com")?;
let store = Store::new()?;
store.insert(QuadRef::new(&ex, &ex, &ex, &ex))?;
store.insert(QuadRef::new(&ex, &ex, &ex, GraphNameRef::DefaultGraph))?;
assert_eq!(vec![NamedOrBlankNode::from(ex)], store.named_graphs().collect::<Result<Vec<_>,_>>()?);

pub fn contains_named_graph<'a>( &self, graph_name: impl Into<NamedOrBlankNodeRef<'a>> ) -> Result<bool, StorageError>

Checks if the store contains a given graph

Usage example:

use oxigraph::store::Store;
use oxigraph::model::{NamedNode, QuadRef};

let ex = NamedNode::new("http://example.com")?;
let store = Store::new()?;
store.insert(QuadRef::new(&ex, &ex, &ex, &ex))?;
assert!(store.contains_named_graph(&ex)?);

pub fn insert_named_graph<'a>( &self, graph_name: impl Into<NamedOrBlankNodeRef<'a>> ) -> Result<bool, StorageError>

Inserts a graph into this store.

Returns true if the graph was not already in the store.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::NamedNodeRef;

let ex = NamedNodeRef::new("http://example.com")?;
let store = Store::new()?;
store.insert_named_graph(ex)?;

assert_eq!(store.named_graphs().collect::<Result<Vec<_>,_>>()?, vec![ex.into_owned().into()]);

pub fn clear_graph<'a>( &self, graph_name: impl Into<GraphNameRef<'a>> ) -> Result<(), StorageError>

Clears a graph from this store.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::{NamedNodeRef, QuadRef};

let ex = NamedNodeRef::new("http://example.com")?;
let quad = QuadRef::new(ex, ex, ex, ex);
let store = Store::new()?;
store.insert(quad)?;
assert_eq!(1, store.len()?);

store.clear_graph(ex)?;
assert!(store.is_empty()?);
assert_eq!(1, store.named_graphs().count());

pub fn remove_named_graph<'a>( &self, graph_name: impl Into<NamedOrBlankNodeRef<'a>> ) -> Result<bool, StorageError>

Removes a graph from this store.

Returns true if the graph was in the store and has been removed.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::{NamedNodeRef, QuadRef};

let ex = NamedNodeRef::new("http://example.com")?;
let quad = QuadRef::new(ex, ex, ex, ex);
let store = Store::new()?;
store.insert(quad)?;
assert_eq!(1, store.len()?);

assert!(store.remove_named_graph(ex)?);
assert!(store.is_empty()?);
assert_eq!(0, store.named_graphs().count());

pub fn clear(&self) -> Result<(), StorageError>

Clears the store.

Usage example:

use oxigraph::store::Store;
use oxigraph::model::*;

let ex = NamedNodeRef::new("http://example.com")?;
let store = Store::new()?;
store.insert(QuadRef::new(ex, ex, ex, ex))?;
store.insert(QuadRef::new(ex, ex, ex, GraphNameRef::DefaultGraph))?;    
assert_eq!(2, store.len()?);

store.clear()?;
assert!(store.is_empty()?);

pub fn flush(&self) -> Result<(), StorageError>

Flushes all buffers and ensures that all writes are saved on disk.

Flushes are automatically done using background threads but might lag a little bit.

pub fn optimize(&self) -> Result<(), StorageError>

Optimizes the database for future workload.

Useful to call after a batch upload or another similar operation.

Warning: Can take hours on huge databases.

pub fn backup( &self, target_directory: impl AsRef<Path> ) -> Result<(), StorageError>

Creates database backup into the target_directory.

After its creation, the backup is usable using Store::open like a regular Oxigraph database and operates independently from the original database.

Warning: Backups are only possible for on-disk databases created using Store::open. Temporary in-memory databases created using Store::new are not compatible with RocksDB backup system.

Warning: An error is raised if the target_directory already exists.

If the target directory is in the same file system as the current database, the database content will not be fully copied but hard links will be used to point to the original database immutable snapshots. This allows cheap regular backups.

If you want to move your data to another RDF storage system, you should have a look at the Store::dump_dataset function instead.

pub fn bulk_loader(&self) -> BulkLoader

Creates a bulk loader allowing to load at lot of data quickly into the store.

Usage example:

use oxigraph::store::Store;
use oxigraph::io::DatasetFormat;
use oxigraph::model::*;

let store = Store::new()?;

// quads file insertion
let file = b"<http://example.com> <http://example.com> <http://example.com> <http://example.com> .";
store.bulk_loader().load_dataset(file.as_ref(), DatasetFormat::NQuads, None)?;

// we inspect the store contents
let ex = NamedNodeRef::new("http://example.com")?;
assert!(store.contains(QuadRef::new(ex, ex, ex, ex))?);

Trait Implementations

impl Clone for Store

fn clone(&self) -> Store

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Display for Store

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.