Module volksdata.graph
Graph module.
A graph is a set of ???s. As such, it guarantees uniqueness of its members and supports common set operations such as addition, removal, iteration, lookup, and boolean operations.
A graph is always backed by a ???. If not specified, a default store is used which is in memory and ephemeral. Triples can be copied from one graph to another, even between graphs backed by different stores.
A graph always has a URI in the form of a ??? of the IRIRef
type, and this is the identifier used if the graph is backed by a store that
supports contexts (named graphs). Identical triples belonging to different
named graphs are stored separately in this case.
Functions
| get (gr_uri, store[, txn]) | Get a graph from a store. |
| list (store[, txn]) | List all graphs in a store. |
| new (store, uri_str, is_ns) | Create a new graph. |
| new_decode (rdf, fmt) | Decode RDF data into a graph. |
Class volksdata.Graph
| volksdata.graph.store | Graph backing store. |
| volksdata.graph.uri | Graph URI. |
| volksdata.graph:__band (gr2[, txn]) | Perform a boolean intersection between two graphs. |
| volksdata.graph:__bor (gr2[, txn]) | Perform a boolean union between two graphs. |
| volksdata.graph:__bxor (gr2[, txn]) | Perform a boolean XOR between two graphs. |
| volksdata.graph:__eq (gr2) | Equality operator (==). |
| volksdata.graph:__len () | Size operator (#). |
| volksdata.graph:__sub (gr2[, txn]) | Perform a boolean subtraction between two graphs. |
| volksdata.graph:__tostring () | String representation of a graph. |
| volksdata.graph:add (trp[, txn]) | Add triples in bulk. |
| volksdata.graph:add_init ([txn]) | Start iterative addition. |
| volksdata.graph:attr (s, p) | Get all o's for given s and p as a table of values. |
| volksdata.graph:connections () | Extract a link map from a graph. |
| volksdata.graph:contains (trp) | Whether a graph contains a triple. |
| volksdata.graph:copy (dest[, s[, p[, o[, txn]]]]) | Copy the contents of a graph into another graph. |
| volksdata.graph:encode (format) | Encode a graph into RDF. |
| volksdata.graph:lookup ([s[, p[, o[, txn]]]]) | Look up triples in graph by pattern. |
| volksdata.graph:remove ([s[, p[, o[, txn]]]]) | Remove triples from a graph. |
| volksdata.graph:term_set (t1, t1_pos, t2, t2_pos) | Create a term set from bound terms in a graph. |
| volksdata.graph:unique_terms (pos) | Return all unique terms in a specified position in a graph. |
Class GraphIterator
| graphiterator:add_done () | Finalize iterative addition. |
| graphiterator:add_iter (spo) | Add one triple to a graph. |
Functions
- get (gr_uri, store[, txn])
-
Get a graph from a store.
Parameters:
- gr_uri Term Graph URI to look up.
- store Store Store to look into. It must be of a type that supports the ??? feature.
- txn Transaction Transaction to perform the lookup within. (optional)
Returns:
-
Graph
Graph matching the provided URI. The graph is an in-memory
copy of the stored one.
nilif not found. - list (store[, txn])
-
List all graphs in a store.
Parameters:
- store Store Store to look into.
- txn Transaction Transaction to perform the lookup within. (optional)
Returns:
-
TermSet
Term set with all the graph URIs found in the
store.
- new (store, uri_str, is_ns)
-
Create a new graph.
Parameters:
- store Store The store to use as a back end. if unspecified, an in-memory embedded store is used. This kind of store is tethered to the lifecycle of the graph it is created with, and may not be used for another graph.
- uri_str string String to use as the graph URI. It may be namespace- prefixed, or fully qualified. If not specified, Volksdata generates a UUID4 URN.
- is_ns
bool
Whether the passed string is a namespace-prefixed URI.
Default is false. If this is true, the
uri_strparameter MUST be passed.
- new_decode (rdf, fmt)
-
Decode RDF data into a graph.
Parameters:
- rdf userdata or string RDF source, either as a string or as an open file handle.
- fmt
string
Encoding format of the RDF data. One of
nt,ttl.
Returns:
- Graph New graph populated with source RDF data.
- int Number of triples parsed. This may be different from the number of triples in the resulting graph.
Class volksdata.Graph
- volksdata.graph.store
-
Graph backing store.
- store
- volksdata.graph.uri
-
Graph URI.
- uri
- volksdata.graph:__band (gr2[, txn])
-
Perform a boolean intersection between two graphs.
This function is accessible via the binary AND (
&) operator.Parameters:
- gr2 Graph Other graph to perform the boolean operation on.
- txn Transaction Transaction to perform the operation within. (optional)
Returns:
-
Graph
New in-memory graph with the operation result.
- volksdata.graph:__bor (gr2[, txn])
-
Perform a boolean union between two graphs.
This function is accessible via the binary OR (
|) operator.Parameters:
- gr2 Graph Other graph to perform the boolean operation on.
- txn Transaction Transaction to perform the operation within. (optional)
Returns:
-
Graph
New in-memory graph with the operation result.
- volksdata.graph:__bxor (gr2[, txn])
-
Perform a boolean XOR between two graphs.
This function is accessible via the binary XOR (
~) operator.Parameters:
- gr2 Graph Other graph to perform the boolean operation on.
- txn Transaction Transaction to perform the operation within. (optional)
Returns:
-
Graph
New in-memory graph with the operation result.
- volksdata.graph:__eq (gr2)
-
Equality operator (
==).Two graphs are evaluated as equals if they have exactly the same triples (under the hood, a set XOR is made and the return value indicates whether the result is empty).
Parameters:
- gr2 Graph Graph to compare to.
Returns:
-
bool
- volksdata.graph:__len ()
-
Size operator (
#).Returns:
-
int
Number of triples in a graph.
- volksdata.graph:__sub (gr2[, txn])
-
Perform a boolean subtraction between two graphs.
This function is accessible via the subtraction (
-) operator.Parameters:
- gr2 Graph Other graph to perform the boolean operation on.
- txn Transaction Transaction to perform the operation within. (optional)
Returns:
-
Graph
New in-memory graph with the operation result.
- volksdata.graph:__tostring ()
-
String representation of a graph.
Displays memory address, URI, and number of triples.
Returns:
- volksdata.graph:add (trp[, txn])
-
Add triples in bulk.
This function adds triples to a graph from a table. It is a simpler alternative to the add_init - add_iter - add_done method that is convenient if the table had previously been created for some other reason.
Parameters:
- trp {Triple,...} Triples to add, as a numerically indexed table of ??? objects.
- txn Transaction Transaction to perform the operation within. (optional)
Returns:
-
int
Number of triples effectively added (excluding duplicates).
- volksdata.graph:add_init ([txn])
-
Start iterative addition.
This function initializes and returns an iterator that can be used to iteratively add triples to a graph with add_iter. Iteration must be finalized with add_done.
Parameters:
- txn Transaction Transaction to perform the operation within. (optional)
Returns:
-
GraphIterator
iterator handle.
- volksdata.graph:attr (s, p)
-
Get all
o's for givensandpas a table of values.Parameters:
- s Term Subject to query.
- p Term Predicate to query.
Returns:
-
TermSet
Object terms found per sp combination.
- volksdata.graph:connections ()
-
Extract a link map from a graph.
A link map is an iterable data structure containing a set of terms connected to a given lookup term in a specific position in the triples of a graphs. Each linked term in its turn has an iterator.
Returns:
-
LinkMap
handle that can be iterated over with iter().
- volksdata.graph:contains (trp)
-
Whether a graph contains a triple.
Parameters:
- trp Triple Triple to check.
Returns:
-
bool
- volksdata.graph:copy (dest[, s[, p[, o[, txn]]]])
-
Copy the contents of a graph into another graph.
The destination graph MUST exist and MAY be non-empty.
The copy MAY be filtered via bound terms in the same way as graph.lookup.
Parameters:
- dest Graph Graph to copy to.
- s Term Bound subject for filtered copy. (optional)
- p Term Bound predicate for filtered copy. (optional)
- o Term Bound object for filtered copy. (optional)
- txn Transaction Transaction to perform the copy within. (optional)
Returns:
-
nil
- volksdata.graph:encode (format)
-
Encode a graph into RDF.
Parameters:
- format
string
RDF encoding format. One of the codecs available in
Volksdata. Currently,
ntandttl.
Returns:
-
func
terator function to generate encoded RDF strings, one chunk
for each iteration. The scope of the chunk is dependent on the requested
format.
- format
string
RDF encoding format. One of the codecs available in
Volksdata. Currently,
- volksdata.graph:lookup ([s[, p[, o[, txn]]]])
-
Look up triples in graph by pattern.
Parameters:
- s Term Bound subject. (optional)
- p Term Bound predicate. (optional)
- o Term Bound object. (optional)
- txn Transaction Transaction to perform the operation within. (optional)
Returns:
- function Iterator function to get lookup results.
- int Number of found triples.
- volksdata.graph:remove ([s[, p[, o[, txn]]]])
-
Remove triples from a graph.
The triples are removed according to a pattern of bound terms. This function uses the same underlying logic as lookup and behaves similarly: triples that match all bound terms are removed.
Parameters:
- s Term Bound subject. (optional)
- p Term Bound predicate. (optional)
- o Term Bound object. (optional)
- txn Transaction Transaction to perform the operation within. (optional)
Returns:
-
int
Number of triples removed.
- volksdata.graph:term_set (t1, t1_pos, t2, t2_pos)
-
Create a term set from bound terms in a graph.
This function requires two terms in two specified positions, and returns a ??? object from the single terms found in triples matching the query terms.
Parameters:
- t1 Term First bound term.
- t1_pos
int
Position of first bound term. One of
Triple.POS_*constants. - t2 Term Second bound term.Term).
- t2_pos
int
Position of second bound term. One of
Triple.POS_*constants.
Returns:
-
TermSet
Results that can be iterated with the
iter()method. - volksdata.graph:unique_terms (pos)
-
Return all unique terms in a specified position in a graph.
Parameters:
- pos
int
Position of terms to query. One of
Triple.POS_*constants.
Returns:
-
TermSet
Results that can be iterated with the
iter()method. - pos
int
Position of terms to query. One of
Class GraphIterator
- graphiterator:add_done ()
-
Finalize iterative addition.
Returns:
-
nil
- graphiterator:add_iter (spo)
-
Add one triple to a graph.
This function can be called multiple times, one per triple, on a previously created iterator. It MUST be finalized with add_done to make the addition effective.
Parameters:
- spo Triple Triple to add.
Returns:
-
nil