From a0c5cf72863bbd9341ba3fd89d46d77e5fcde3fe Mon Sep 17 00:00:00 2001 From: Tpt Date: Wed, 5 Aug 2020 18:47:59 +0200 Subject: [PATCH] Adds links to the code documentation --- README.md | 7 +++- lib/src/io/format.rs | 2 +- lib/src/io/read.rs | 8 ++-- lib/src/lib.rs | 16 +++++--- lib/src/model/blank_node.rs | 2 +- lib/src/model/vocab.rs | 4 +- lib/src/sparql/error.rs | 5 +-- lib/src/sparql/mod.rs | 7 ++-- lib/src/sparql/model.rs | 2 +- lib/src/store/memory.rs | 44 ++++++++++++++------- lib/src/store/rocksdb.rs | 66 ++++++++++++++++++------------- lib/src/store/sled.rs | 78 ++++++++++++++++++++++++------------- 12 files changed, 148 insertions(+), 93 deletions(-) diff --git a/README.md b/README.md index 2380fc8d..713daa87 100644 --- a/README.md +++ b/README.md @@ -7,19 +7,22 @@ Oxigraph Oxigraph is a work in progress graph database implementing the [SPARQL](https://www.w3.org/TR/sparql11-overview/) standard. There is no released version yet. +The storage format is not stable yet and may be brocken at any time. -Its goal is to provide a compliant, safe and fast graph database based on the [RocksDB](https://rocksdb.org/) key-value store. +Its goal is to provide a compliant, safe and fast graph database based on the [RocksDB](https://rocksdb.org/) and [Sled](https://sled.rs/) key-value stores. It is written in Rust. +It also provides a set of utility functions for reading, writing and processing RDF files. It is split into multiple parts: * The `lib` directory contains the database written as a Rust library. * The `python` directory contains bindings to use Oxigraph in Python. See [its README](https://github.com/oxigraph/oxigraph/blob/master/python/README.md) for the Python bindings documentation. * The `js` directory contains bindings to use Oxigraph in JavaScript with the help of WebAssembly. See [its README](https://github.com/oxigraph/oxigraph/blob/master/js/README.md) for the JS bindings documentation. -* The `server` directory contains a stand-alone binary of a web server implementing the [SPARQL 1.1 Protocol](https://www.w3.org/TR/sparql11-protocol/). +* The `server` directory contains a stand-alone binary of a web server implementing the [SPARQL 1.1 Protocol](https://www.w3.org/TR/sparql11-protocol/). It uses the [RocksDB](https://rocksdb.org/) key-value store. * The `wikibase` directory contains a stand-alone binary of a web server able to synchronize with a [Wikibase instance](https://wikiba.se/). Are currently implemented: * [SPARQL 1.1 Query](https://www.w3.org/TR/sparql11-query/) except `FROM` and `FROM NAMED`. +* [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/). * [Turtle](https://www.w3.org/TR/turtle/), [TriG](https://www.w3.org/TR/trig/), [N-Triples](https://www.w3.org/TR/n-triples/), [N-Quads](https://www.w3.org/TR/n-quads/) and [RDF XML](https://www.w3.org/TR/rdf-syntax-grammar/) RDF serialization formats for both data ingestion and retrieval using the [Rio library](https://github.com/oxigraph/rio). * [SPARQL Query Results XML Format](http://www.w3.org/TR/rdf-sparql-XMLres/) and [SPARQL Query Results JSON Format](https://www.w3.org/TR/sparql11-results-json/). diff --git a/lib/src/io/format.rs b/lib/src/io/format.rs index 5789e478..8e2bfac1 100644 --- a/lib/src/io/format.rs +++ b/lib/src/io/format.rs @@ -1,6 +1,6 @@ /// A file serialization format. /// -/// Is implemented by `GraphFormat` for graph files and `DatasetFormat` for dataset files. +/// Is implemented by [`GraphFormat`](../enum.GraphFormat.html) for graph files and [`DatasetFormat`](../enum.DatasetFormat.html) for dataset files. #[deprecated(note = "Use directly the methods on the implementing types")] pub trait FileSyntax: Sized { /// Its canonical IRI according to the [Unique URIs for file formats registry](https://www.w3.org/ns/formats/). diff --git a/lib/src/io/read.rs b/lib/src/io/read.rs index 89eaa9c7..0d90037e 100644 --- a/lib/src/io/read.rs +++ b/lib/src/io/read.rs @@ -12,7 +12,7 @@ use std::collections::HashMap; use std::io; use std::io::BufRead; -/// A reader for RDF graph serialization formats. +/// Parsers for RDF graph serialization formats. /// /// It currently supports the following formats: /// * [N-Triples](https://www.w3.org/TR/n-triples/) (`GraphFormat::NTriples`) @@ -87,7 +87,7 @@ impl GraphParser { } /// Allows reading triples. -/// Could be built using a `GraphParser`. +/// Could be built using a [`GraphParser`](struct.GraphParser.html). /// /// ``` /// use oxigraph::io::{GraphFormat, GraphParser}; @@ -170,7 +170,7 @@ impl TripleReader { } } -/// A reader for RDF dataset serialization formats. +/// A parser for RDF dataset serialization formats. /// /// It currently supports the following formats: /// * [N-Quads](https://www.w3.org/TR/n-quads/) (`DatasetFormat::NQuads`) @@ -241,7 +241,7 @@ impl DatasetParser { } /// Allows reading quads. -/// Could be built using a `DatasetParser`. +/// Could be built using a [`DatasetParser`](struct.DatasetParser.html). /// /// ``` /// use oxigraph::io::{DatasetFormat, DatasetParser}; diff --git a/lib/src/lib.rs b/lib/src/lib.rs index d6e2b965..43eb4ff7 100644 --- a/lib/src/lib.rs +++ b/lib/src/lib.rs @@ -2,17 +2,19 @@ //! //! Its goal is to provide a compliant, safe and fast graph database. //! -//! It currently provides three `Store` implementation providing [SPARQL 1.1 query](https://www.w3.org/TR/sparql11-query/) capability: -//! * `MemoryStore`: a simple in memory implementation. -//! * `RocksDbStore`: a file system implementation based on the [RocksDB](https://rocksdb.org/) key-value store. +//! It currently provides three store implementations providing [SPARQL 1.1 query](https://www.w3.org/TR/sparql11-query/) capability: +//! * [`MemoryStore`](store/memory/struct.MemoryStore.html): a simple in memory implementation. +//! * [`RocksDbStore`](store/rocksdb/struct.RocksDbStore.html): a file system implementation based on the [RocksDB](https://rocksdb.org/) key-value store. //! It requires the `"rocksdb"` feature to be activated. -//! It also requires the [clang](https://clang.llvm.org/) compiler to be installed. -//! * `SledStore`: another file system implementation based on the [Sled](https://sled.rs/) key-value store. +//! The `"rocksdb"` requires the [clang](https://clang.llvm.org/) compiler to be installed. +//! * [`SledStore`](store/sled/struct.SledStore.html): another file system implementation based on the [Sled](https://sled.rs/) key-value store. //! It requires the `"sled"` feature to be activated. //! Sled is much faster to build than RockDB and does not require a C++ compiler. //! However, Sled is still in developpment, less tested and data load seems much slower than RocksDB. //! -//! Usage example with the `MemoryStore`: +//! It also provides a set of utility functions for reading, writing and processing RDF files. +//! +//! Usage example with the [`MemoryStore`](store/memory/struct.MemoryStore.html): //! //! ``` //! use oxigraph::MemoryStore; @@ -46,6 +48,8 @@ unsafe_code, unused_qualifications )] +#![doc(html_favicon_url = "https://raw.githubusercontent.com/oxigraph/oxigraph/master/logo.svg")] +#![doc(html_logo_url = "https://raw.githubusercontent.com/oxigraph/oxigraph/master/logo.svg")] #![warn( clippy::unimplemented, clippy::cast_lossless, diff --git a/lib/src/model/blank_node.rs b/lib/src/model/blank_node.rs index 5c395f76..9d4cd7ed 100644 --- a/lib/src/model/blank_node.rs +++ b/lib/src/model/blank_node.rs @@ -322,7 +322,7 @@ fn to_integer_id(id: &str) -> Option { Some(value) } -/// An error raised during `BlankNode` validation. +/// An error raised during [`BlankNode`](struct.BlankNode.html) IDs validation. #[allow(missing_copy_implementations)] #[derive(Debug)] pub struct BlankNodeIdParseError {} diff --git a/lib/src/model/vocab.rs b/lib/src/model/vocab.rs index f1f9e0c0..225cee78 100644 --- a/lib/src/model/vocab.rs +++ b/lib/src/model/vocab.rs @@ -1,4 +1,4 @@ -//! Provides ready to use `NamedNode`s for basic RDF vocabularies +//! Provides ready to use [`NamedNodeRef`s](struct.NamedNodeRef.html) for basic RDF vocabularies pub mod rdf { //! [RDF 1.1](https://www.w3.org/TR/rdf11-concepts/) vocabulary @@ -109,7 +109,7 @@ pub mod rdfs { } pub mod xsd { - //! `NamedNode`s for [RDF compatible XSD datatypes](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-compatible-xsd-types) + //! [RDF compatible XSD datatypes](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-compatible-xsd-types) use crate::model::named_node::NamedNodeRef; /// true, false diff --git a/lib/src/sparql/error.rs b/lib/src/sparql/error.rs index d42693c2..f7e489a3 100644 --- a/lib/src/sparql/error.rs +++ b/lib/src/sparql/error.rs @@ -6,10 +6,7 @@ use std::error; use std::fmt; use std::io; -/// SPARQL evaluation error. -/// -/// The `wrap` method allows us to make this type wrap any implementation of `std::error::Error`. -/// This type also avoids heap allocations for the most common cases of evaluation errors. +/// A SPARQL evaluation error. #[derive(Debug)] #[non_exhaustive] pub enum EvaluationError { diff --git a/lib/src/sparql/mod.rs b/lib/src/sparql/mod.rs index a8c66a46..c0a1d99a 100644 --- a/lib/src/sparql/mod.rs +++ b/lib/src/sparql/mod.rs @@ -169,7 +169,7 @@ impl QueryOptions { self } - /// Use a given `ServiceHandler` to execute SPARQL SERVICE calls + /// Use a given [`ServiceHandler`](trait.ServiceHandler.html) to execute [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/) SERVICE calls. pub fn with_service_handler(mut self, service_handler: impl ServiceHandler + 'static) -> Self { self.service_handler = Rc::new(ErrorConversionServiceHandler { handler: service_handler, @@ -178,9 +178,10 @@ impl QueryOptions { } } -/// Handler for SPARQL SERVICEs. +/// Handler for [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/) SERVICE. /// -/// Might be used to implement [SPARQL 1.1 Federated Query](https://www.w3.org/TR/sparql11-federated-query/) +/// Should be given to [`QueryOptions`](struct.QueryOptions.html#method.with_service_handler) +/// before evaluating a SPARQL query that uses SERVICE calls. /// /// ``` /// use oxigraph::MemoryStore; diff --git a/lib/src/sparql/model.rs b/lib/src/sparql/model.rs index 08a8afab..4d87a1c8 100644 --- a/lib/src/sparql/model.rs +++ b/lib/src/sparql/model.rs @@ -298,7 +298,7 @@ pub struct QuerySolution { } impl QuerySolution { - /// Returns a value for a given position in the tuple (`usize`) or a given variable name (`&str` or `Variable`) + /// Returns a value for a given position in the tuple ([`usize`](https://doc.rust-lang.org/std/primitive.usize.html)) or a given variable name ([`&str`](https://doc.rust-lang.org/std/primitive.str.html) or [`Variable`](struct.Variable.html)) /// /// ```ignore /// let foo = solution.get("foo"); // Get the value of the variable ?foo if it exists diff --git a/lib/src/store/memory.rs b/lib/src/store/memory.rs index 8c03c2b7..76d6afc4 100644 --- a/lib/src/store/memory.rs +++ b/lib/src/store/memory.rs @@ -24,7 +24,7 @@ use std::{fmt, io}; /// In-memory store. /// It encodes a [RDF dataset](https://www.w3.org/TR/rdf11-concepts/#dfn-rdf-dataset) and allows to query and update it using SPARQL. -/// It is cheap to build using the `MemoryStore::new()` method. +/// It is cheap to build using the [`MemoryStore::new()`](#method.new) method. /// /// Usage example: /// ``` @@ -77,7 +77,7 @@ impl Default for MemoryStore { } impl MemoryStore { - /// Constructs a new `MemoryStore` + /// Constructs a new [`MemoryStore`]() pub fn new() -> Self { Self { indexes: Arc::new(RwLock::default()), @@ -212,10 +212,10 @@ impl MemoryStore { self.indexes().spog.is_empty() } - /// Executes a transaction. + /// Executes an ACID transaction. /// /// The transaction is executed if the given closure returns `Ok`. - /// Nothing is done if the clusre returns `Err`. + /// The transaction if rollbacked if the closure returns `Err`. /// /// Usage example: /// ``` @@ -283,8 +283,12 @@ impl MemoryStore { /// # Result::<_,Box>::Ok(()) /// ``` /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Warning: This functions saves the triples during the parsing. + /// If the parsing fails in the middle of the file, the triples read before stay in the store. + /// Use a (memory greedy) [transaction](#method.transaction) if you do not want that. + /// + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. pub fn load_graph<'a>( &self, reader: impl BufRead, @@ -318,8 +322,12 @@ impl MemoryStore { /// # Result::<_,Box>::Ok(()) /// ``` /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Warning: This functions saves the quads during the parsing. + /// If the parsing fails in the middle of the file, the quads read before stay in the store. + /// Use a (memory greedy) [transaction](#method.transaction) if you do not want that. + /// + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. pub fn load_dataset( &self, reader: impl BufRead, @@ -376,8 +384,8 @@ impl MemoryStore { /// # std::io::Result::Ok(()) /// ``` /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. pub fn dump_graph<'a>( &self, writer: impl Write, @@ -410,8 +418,8 @@ impl MemoryStore { /// # std::io::Result::Ok(()) /// ``` /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. pub fn dump_dataset(&self, writer: impl Write, format: DatasetFormat) -> Result<(), io::Error> { dump_dataset( self.quads_for_pattern(None, None, None, None).map(Ok), @@ -930,7 +938,7 @@ fn quad_map_flatten<'a, T: Copy>(gspo: &'a QuadMap) -> impl Iterator); impl MemoryPreparedQuery { @@ -940,7 +948,7 @@ impl MemoryPreparedQuery { } } -/// Allows to insert and delete quads during a transaction with the `MemoryStore`. +/// Allows to insert and delete quads during an ACID transaction with the [`MemoryStore`](struct.MemoryStore.html). pub struct MemoryTransaction { ops: Vec, } @@ -973,6 +981,10 @@ impl MemoryTransaction { /// assert_eq!(vec![Quad::new(ex.clone(), ex.clone(), ex.clone(), None)], results); /// # Result::<_, oxigraph::sparql::EvaluationError>::Ok(()) /// ``` + /// + /// If the file parsing fails in the middle of the file, the triples read before are still + /// considered by the transaction. Rollback the transaction by making the transaction closure + /// return an error if you don't want that. pub fn load_graph<'a>( &mut self, reader: impl BufRead, @@ -1014,6 +1026,10 @@ impl MemoryTransaction { /// assert_eq!(vec![Quad::new(ex.clone(), ex.clone(), ex.clone(), Some(ex.into()))], results); /// # Result::<_, oxigraph::sparql::EvaluationError>::Ok(()) /// ``` + /// + /// If the file parsing fails in the middle of the file, the quads read before are still + /// considered by the transaction. Rollback the transaction by making the transaction closure + /// return an error if you don't want that. pub fn load_dataset( &mut self, reader: impl BufRead, diff --git a/lib/src/store/rocksdb.rs b/lib/src/store/rocksdb.rs index 4f2dfeab..1d7a81eb 100644 --- a/lib/src/store/rocksdb.rs +++ b/lib/src/store/rocksdb.rs @@ -81,7 +81,7 @@ const COLUMN_FAMILIES: [&str; 7] = [ const MAX_TRANSACTION_SIZE: usize = 1024; impl RocksDbStore { - /// Opens a `RocksDbStore` + /// Opens a [`RocksDbStore`]() pub fn open(path: impl AsRef) -> Result { let mut options = Options::default(); options.create_if_missing(true); @@ -95,7 +95,7 @@ impl RocksDbStore { /// Executes a [SPARQL 1.1 query](https://www.w3.org/TR/sparql11-query/). /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.query) for a usage example. pub fn query( &self, query: impl TryInto>, @@ -107,7 +107,7 @@ impl RocksDbStore { /// Prepares a [SPARQL 1.1 query](https://www.w3.org/TR/sparql11-query/) and returns an object that could be used to execute it. /// It is useful if you want to execute multiple times the same SPARQL query. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.prepare_query) for a usage example. pub fn prepare_query( &self, query: impl TryInto>, @@ -122,7 +122,7 @@ impl RocksDbStore { /// Retrieves quads with a filter on each quad component /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.quads_for_pattern) for a usage example. pub fn quads_for_pattern( &self, subject: Option>, @@ -164,12 +164,14 @@ impl RocksDbStore { .is_none() } - /// Executes a transaction. + /// Executes an ACID transaction. /// /// The transaction is executed if the given closure returns `Ok`. - /// Nothing is done if the closure returns `Err`. + /// The transaction is rollbacked if the closure returns `Err`. /// - /// See `MemoryStore` for a usage example. + /// The transaction data are stored in memory while the transaction is not committed or rollbacked. + /// + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.transaction) for a usage example. pub fn transaction<'a, E: From>( &'a self, f: impl FnOnce(&mut RocksDbTransaction<'a>) -> Result<(), E>, @@ -187,12 +189,12 @@ impl RocksDbStore { /// Loads a graph file (i.e. triples) into the store /// /// Warning: This functions saves the triples in batch. If the parsing fails in the middle of the file, - /// only a part of it may be written. Use a (memory greedy) transaction if you do not want that. + /// only a part of it may be written. Use a (memory greedy) [transaction](#method.transaction) if you do not want that. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.load_graph) for a usage example. /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. /// Errors related to data loading into the store use the other error kinds. pub fn load_graph<'a>( &self, @@ -215,12 +217,12 @@ impl RocksDbStore { /// Loads a dataset file (i.e. quads) into the store. /// /// Warning: This functions saves the quads in batch. If the parsing fails in the middle of the file, - /// only a part of it may be written. Use a (memory greedy) transaction if you do not want that. + /// only a part of it may be written. Use a (memory greedy) [transaction](#method.transaction) if you do not want that. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.load_dataset) for a usage example. /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. /// Errors related to data loading into the store use the other error kinds. pub fn load_dataset( &self, @@ -234,6 +236,7 @@ impl RocksDbStore { } /// Adds a quad to this store. + /// This operation is atomic and could not leave the store in a bad state. pub fn insert<'a>(&self, quad: impl Into>) -> Result<(), io::Error> { let mut transaction = self.auto_batch_writer(); let quad = transaction.encode_quad(quad.into())?; @@ -242,6 +245,7 @@ impl RocksDbStore { } /// Removes a quad from this store. + /// This operation is atomic and could not leave the store in a bad state. pub fn remove<'a>(&self, quad: impl Into>) -> Result<(), io::Error> { if let Some(quad) = self.get_encoded_quad(quad.into())? { let mut transaction = self.auto_batch_writer(); @@ -254,7 +258,7 @@ impl RocksDbStore { /// Dumps a store graph into a file. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.dump_graph) for a usage example. pub fn dump_graph<'a>( &self, writer: impl Write, @@ -271,7 +275,7 @@ impl RocksDbStore { /// Dumps the store dataset into a file. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.dump_dataset) for a usage example. pub fn dump_dataset(&self, writer: impl Write, syntax: DatasetFormat) -> Result<(), io::Error> { dump_dataset( self.quads_for_pattern(None, None, None, None), @@ -579,7 +583,7 @@ impl ReadableEncodedStore for RocksDbStore { } } -/// A prepared [SPARQL query](https://www.w3.org/TR/sparql11-query/) for the `RocksDbStore`. +/// A prepared [SPARQL query](https://www.w3.org/TR/sparql11-query/) for the [`RocksDbStore`](struct.RocksDbStore.html). pub struct RocksDbPreparedQuery(SimplePreparedQuery); impl RocksDbPreparedQuery { @@ -683,7 +687,7 @@ impl WritableEncodedStore for AutoBatchWriter<'_> { } } -/// Allows inserting and deleting quads during a transaction with the `RocksDbStore`. +/// Allows inserting and deleting quads during an ACID transaction with the [`RocksDbStore`](struct.RocksDbStore.html). pub struct RocksDbTransaction<'a> { store: &'a RocksDbStore, batch: WriteBatch, @@ -695,13 +699,17 @@ impl RocksDbTransaction<'_> { /// Loads a graph file (i.e. triples) into the store during the transaction. /// /// Warning: Because the load happens during a transaction, - /// the full file content might be temporarily stored in main memory. + /// the full file content is temporarily stored in main memory. /// Do not use for big files. /// - /// See `MemoryTransaction` for a usage example. + /// See [`MemoryTransaction`](../memory/struct.MemoryTransaction.html#method.load_graph) for a usage example. + /// + /// If the file parsing fails in the middle of the file, the triples read before are still + /// considered by the transaction. Rollback the transaction by making the transaction closure + /// return an error if you don't want that. /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. pub fn load_graph<'a>( &mut self, reader: impl BufRead, @@ -716,13 +724,17 @@ impl RocksDbTransaction<'_> { /// Loads a dataset file (i.e. quads) into the store. into the store during the transaction. /// /// Warning: Because the load happens during a transaction, - /// the full file content might be temporarily stored in main memory. + /// the full file content is temporarily stored in main memory. /// Do not use for big files. /// - /// See `MemoryTransaction` for a usage example. + /// See [`MemoryTransaction`](../memory/struct.MemoryTransaction.html#method.load_dataset) for a usage example. + /// + /// If the file parsing fails in the middle of the file, the quads read before are still + /// considered by the transaction. Rollback the transaction by making the transaction closure + /// return an error if you don't want that. /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. pub fn load_dataset( &mut self, reader: impl BufRead, diff --git a/lib/src/store/sled.rs b/lib/src/store/sled.rs index 3a8f8d50..3dfe6276 100644 --- a/lib/src/store/sled.rs +++ b/lib/src/store/sled.rs @@ -29,7 +29,7 @@ use std::{fmt, io, str}; /// /// To use it, the `"sled"` feature needs to be activated. /// -/// Warning: quad insertions and deletions are not (yet) atomic. +/// Warning: Sled is not stable yet and might break its storage format. /// /// Usage example: /// ``` @@ -77,12 +77,12 @@ type EncodedQuad = crate::store::numeric_encoder::EncodedQuad; //TODO: indexes for the default graph and indexes for the named graphs (no more Optional and space saving) impl SledStore { - /// Opens a temporary `SledStore` that will be deleted after drop. + /// Creates a temporary [`SledStore`]() that will be deleted after drop. pub fn new() -> Result { Self::do_open(&Config::new().temporary(true)) } - /// Opens a `SledStore` + /// Opens a [`SledStore`]() and creates it if it does not exist yet. pub fn open(path: impl AsRef) -> Result { Self::do_open(&Config::new().path(path)) } @@ -97,7 +97,7 @@ impl SledStore { /// Executes a [SPARQL 1.1 query](https://www.w3.org/TR/sparql11-query/). /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.query) for a usage example. pub fn query( &self, query: impl TryInto>, @@ -108,7 +108,7 @@ impl SledStore { /// Prepares a [SPARQL 1.1 query](https://www.w3.org/TR/sparql11-query/) and returns an object that could be used to execute it. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.prepare_query) for a usage example. pub fn prepare_query( &self, query: impl TryInto>, @@ -123,7 +123,7 @@ impl SledStore { /// Retrieves quads with a filter on each quad component /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.quads_for_pattern) for a usage example. pub fn quads_for_pattern( &self, subject: Option>, @@ -160,10 +160,10 @@ impl SledStore { self.quads.is_empty() } - /// Executes a transaction. + /// Executes an ACID transaction. /// /// The transaction is executed if the given closure returns `Ok`. - /// Nothing is done if the closure returns `Err`. + /// The transaction is rollbacked if the closure returns `Err`. /// /// Usage example: /// ``` @@ -197,13 +197,16 @@ impl SledStore { /// Loads a graph file (i.e. triples) into the store /// - /// Warning: This functions saves the triples in batch. If the parsing fails in the middle of the file, - /// only a part of it may be written. Use a (memory greedy) transaction if you do not want that. + /// Warning: This functions saves the triples in a not atomic way. If the parsing fails in the middle of the file, + /// only a part of it may be written to the store. + /// Also, this method is optimized for performances and is not atomic. + /// It might leave the store in a bad state if a crash happens during a triple insertion. + /// Use a (memory greedy) [transaction](#method.transaction) if you do not want that. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.load_graph) for a usage example. /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. /// Errors related to data loading into the store use the other error kinds. pub fn load_graph<'a>( &self, @@ -219,13 +222,16 @@ impl SledStore { /// Loads a dataset file (i.e. quads) into the store. /// - /// Warning: This functions saves the quads in batch. If the parsing fails in the middle of the file, - /// only a part of it may be written. Use a (memory greedy) transaction if you do not want that. + /// Warning: This functions saves the triples in a not atomic way. If the parsing fails in the middle of the file, + /// only a part of it may be written to the store. + /// Also, this method is optimized for performances and is not atomic. + /// It might leave the store in a bad state if a crash happens during a quad insertion. + /// Use a (memory greedy) [transaction](#method.transaction) if you do not want that. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.load_dataset) for a usage example. /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. /// Errors related to data loading into the store use the other error kinds. pub fn load_dataset( &self, @@ -239,6 +245,10 @@ impl SledStore { } /// Adds a quad to this store. + /// + /// This method is optimized for performances and is not atomic. + /// It might leave the store in a bad state if a crash happens during the insertion. + /// Use a (memory greedy) [transaction](#method.transaction) if you do not want that. pub fn insert<'a>(&self, quad: impl Into>) -> Result<(), io::Error> { let mut this = self; let quad = this.encode_quad(quad.into())?; @@ -246,6 +256,10 @@ impl SledStore { } /// Removes a quad from this store. + /// + /// This method is optimized for performances and is not atomic. + /// It might leave the store in a bad state if a crash happens during the removal. + /// Use a (memory greedy) [transaction](#method.transaction) if you do not want that. pub fn remove<'a>(&self, quad: impl Into>) -> Result<(), io::Error> { if let Some(quad) = self.get_encoded_quad(quad.into())? { let mut this = self; @@ -257,7 +271,7 @@ impl SledStore { /// Dumps a store graph into a file. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.dump_graph) for a usage example. pub fn dump_graph<'a>( &self, writer: impl Write, @@ -274,7 +288,7 @@ impl SledStore { /// Dumps the store dataset into a file. /// - /// See `MemoryStore` for a usage example. + /// See [`MemoryStore`](../memory/struct.MemoryStore.html#method.dump_dataset) for a usage example. pub fn dump_dataset(&self, writer: impl Write, format: DatasetFormat) -> Result<(), io::Error> { dump_dataset( self.quads_for_pattern(None, None, None, None), @@ -584,7 +598,7 @@ impl<'a> WritableEncodedStore for &'a SledStore { } } -/// Allows inserting and deleting quads during a transaction with the `SeldStore`. +/// Allows inserting and deleting quads during an ACID transaction with the [`SledStore`](struct.SledStore.html). pub struct SledTransaction<'a> { quads: &'a TransactionalTree, id2str: &'a TransactionalTree, @@ -597,10 +611,14 @@ impl SledTransaction<'_> { /// the full file content might be temporarily stored in main memory. /// Do not use for big files. /// - /// See `MemoryTransaction` for a usage example. + /// See [`MemoryTransaction`](../memory/struct.MemoryTransaction.html#method.load_graph) for a usage example. /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// If the file parsing fails in the middle of the file, the triples read before are still + /// considered by the transaction. Rollback the transaction by making the transaction closure + /// return an error if you don't want that. + /// + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. pub fn load_graph<'a>( &self, reader: impl BufRead, @@ -619,10 +637,14 @@ impl SledTransaction<'_> { /// the full file content might be temporarily stored in main memory. /// Do not use for big files. /// - /// See `MemoryTransaction` for a usage example. + /// See [`MemoryTransaction`](../memory/struct.MemoryTransaction.html#method.load_dataset) for a usage example. + /// + /// If the file parsing fails in the middle of the file, the quads read before are still + /// considered by the transaction. Rollback the transaction by making the transaction closure + /// return an error if you don't want that. /// - /// Errors related to parameter validation like the base IRI use the `INVALID_INPUT` error kind. - /// Errors related to a bad syntax in the loaded file use the `INVALID_DATA` error kind. + /// Errors related to parameter validation like the base IRI use the [`InvalidInput`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidInput) error kind. + /// Errors related to a bad syntax in the loaded file use the [`InvalidData`](https://doc.rust-lang.org/std/io/enum.ErrorKind.html#variant.InvalidData) error kind. pub fn load_dataset( &self, reader: impl BufRead, @@ -903,7 +925,7 @@ impl From> for ConflictableTransactionErr } } -/// A prepared [SPARQL query](https://www.w3.org/TR/sparql11-query/) for the `SledStore`. +/// A prepared [SPARQL query](https://www.w3.org/TR/sparql11-query/) for the [`SledStore`](struct.SledStore.html). pub struct SledPreparedQuery(SimplePreparedQuery); impl SledPreparedQuery {