Modules¶
stardog.connection¶
Connect to Stardog databases.
-
class
stardog.connection.
Connection
(database, endpoint=None, username=None, password=None)[source]¶ Bases:
object
Database Connection.
This is the entry point for all user-related operations on a Stardog database
-
__init__
(database, endpoint=None, username=None, password=None)[source]¶ Initializes a connection to a Stardog database.
- Parameters
database (str) – Name of the database
endpoint (str) – Url of the server endpoint. Defaults to http://localhost:5820
username (str, optional) – Username to use in the connection
password (str, optional) – Password to use in the connection
Examples
>>> conn = Connection('db', endpoint='http://localhost:9999', username='admin', password='admin')
-
add
(content, graph_uri=None)[source]¶ Adds data to the database.
- Parameters
content (Content) – Data to add
graph_uri (str, optional) – Named graph into which to add the data
- Raises
stardog.exceptions.TransactionException – If not currently in a transaction
Examples
>>> conn.add(File('example.ttl'), graph_uri='urn:graph')
-
ask
(query, **kwargs)[source]¶ Executes a SPARQL ask query.
- Parameters
query (str) – SPARQL query
base_uri (str, optional) – Base URI for the parsing of the query
limit (int, optional) – Maximum number of results to return
offset (int, optional) – Offset into the result set
timeout (int, optional) – Number of ms after which the query should timeout. 0 or less implies no timeout
reasoning (bool, optional) – Enable reasoning for the query
bindings (dict, optional) – Map between query variables and their values
- Returns
Result of ask query
- Return type
bool
Examples
>>> conn.ask('ask {:subj :pred :obj}', reasoning=True)
-
begin
(**kwargs)[source]¶ Begins a transaction.
- Parameters
reasoning (bool, optional) – Enable reasoning for all queries inside the transaction. If the transaction does not have reasoning enabled, queries within will not be able to use reasoning.
- Returns
Transaction ID
- Return type
str
- Raises
stardog.exceptions.TransactionException – If already in a transaction
-
clear
(graph_uri=None)[source]¶ Removes all data from the database or specific named graph.
- Parameters
graph_uri (str, optional) – Named graph from which to remove data
- Raises
stardog.exceptions.TransactionException – If currently not in a transaction
Examples
clear a specific named graph
>>> conn.clear('urn:graph')
clear the whole database
>>> conn.clear()
-
commit
()[source]¶ Commits the current transaction.
- Raises
stardog.exceptions.TransactionException – If currently not in a transaction
-
explain
(query, base_uri=None)[source]¶ Explains the evaluation of a SPARQL query.
- Parameters
query (str) – SPARQL query
base_uri (str, optional) – Base URI for the parsing of the query
- Returns
Query explanation
- Return type
str
-
explain_inconsistency
(graph_uri=None)[source]¶ Explains why the database or a named graph is inconsistent.
- Parameters
graph_uri (str, optional) – Named graph for which to explain inconsistency
- Returns
Explanation results
- Return type
dict
-
explain_inference
(content)[source]¶ Explains the given inference results.
- Parameters
content (Content) – Data from which to provide explanations
- Returns
Explanation results
- Return type
dict
Examples
>>> conn.explain_inference(File('inferences.ttl'))
-
export
(content_type='text/turtle', stream=False, chunk_size=10240)[source]¶ Exports the contents of the database.
- Parameters
content_type (str) – RDF content type. Defaults to ‘text/turtle’
stream (bool) – Chunk results? Defaults to False
chunk_size (int) – Number of bytes to read per chunk when streaming. Defaults to 10240
- Returns
If stream = False
- Return type
str
- Returns
If stream = True
- Return type
gen
Examples
no streaming
>>> contents = conn.export()
streaming
>>> with conn.export(stream=True) as stream: contents = ''.join(stream)
-
graph
(query, content_type='text/turtle', **kwargs)[source]¶ Executes a SPARQL graph query.
- Parameters
query (str) – SPARQL query
base_uri (str, optional) – Base URI for the parsing of the query
limit (int, optional) – Maximum number of results to return
offset (int, optional) – Offset into the result set
timeout (int, optional) – Number of ms after which the query should timeout. 0 or less implies no timeout
reasoning (bool, optional) – Enable reasoning for the query
bindings (dict, optional) – Map between query variables and their values
content_type (str) – Content type for results. Defaults to ‘text/turtle’
- Returns
Results in format given by content_type
- Return type
str
Examples
>>> conn.graph('construct {?s ?p ?o} where {?s ?p ?o}', offset=100, limit=100, reasoning=True)
bindings
>>> conn.graph('construct {?s ?p ?o} where {?s ?p ?o}', bindings={'o': '<urn:a>'})
-
is_consistent
(graph_uri=None)[source]¶ Checks if the database or named graph is consistent wrt its schema.
- Parameters
graph_uri (str, optional) – Named graph from which to check consistency
- Returns
Database consistency state
- Return type
bool
-
paths
(query, content_type='application/sparql-results+json', **kwargs)[source]¶ Executes a SPARQL paths query.
- Parameters
query (str) – SPARQL query
base_uri (str, optional) – Base URI for the parsing of the query
limit (int, optional) – Maximum number of results to return
offset (int, optional) – Offset into the result set
timeout (int, optional) – Number of ms after which the query should timeout. 0 or less implies no timeout
reasoning (bool, optional) – Enable reasoning for the query
bindings (dict, optional) – Map between query variables and their values
content_type (str) – Content type for results. Defaults to ‘application/sparql-results+json’
- Returns
if content_type=’application/sparql-results+json’.
- Return type
dict
- Returns
other content types.
- Return type
str
Examples
>>> conn.paths('paths start ?x = :subj end ?y = :obj via ?p', reasoning=True)
-
remove
(content, graph_uri=None)[source]¶ Removes data from the database.
- Parameters
content (Content) – Data to add
graph_uri (str, optional) – Named graph from which to remove the data
- Raises
stardog.exceptions.TransactionException – If currently not in a transaction
Examples
>>> conn.remove(File('example.ttl'), graph_uri='urn:graph')
-
rollback
()[source]¶ Rolls back the current transaction.
- Raises
stardog.exceptions.TransactionException – If currently not in a transaction
-
select
(query, content_type='application/sparql-results+json', **kwargs)[source]¶ Executes a SPARQL select query.
- Parameters
query (str) – SPARQL query
base_uri (str, optional) – Base URI for the parsing of the query
limit (int, optional) – Maximum number of results to return
offset (int, optional) – Offset into the result set
timeout (int, optional) – Number of ms after which the query should timeout. 0 or less implies no timeout
reasoning (bool, optional) – Enable reasoning for the query
bindings (dict, optional) – Map between query variables and their values
content_type (str, optional) – Content type for results. Defaults to ‘application/sparql-results+json’
- Returns
If content_type=’application/sparql-results+json’
- Return type
dict
- Returns
Other content types
- Return type
str
Examples
>>> conn.select('select * {?s ?p ?o}', offset=100, limit=100, reasoning=True)
bindings
>>> conn.select('select * {?s ?p ?o}', bindings={'o': '<urn:a>'})
-
size
(exact=False)[source]¶ Database size.
- Parameters
exact (bool, optional) – Calculate the size exactly. Defaults to False
- Returns
The number of elements in database
- Return type
int
-
update
(query, **kwargs)[source]¶ Executes a SPARQL update query.
- Parameters
query (str) – SPARQL query
base_uri (str, optional) – Base URI for the parsing of the query
limit (int, optional) – Maximum number of results to return
offset (int, optional) – Offset into the result set
timeout (int, optional) – Number of ms after which the query should timeout. 0 or less implies no timeout
reasoning (bool, optional) – Enable reasoning for the query
bindings (dict, optional) – Map between query variables and their values
Examples
>>> conn.update('delete where {?s ?p ?o}')
-
-
class
stardog.connection.
Docs
(conn)[source]¶ Bases:
object
BITES: Document Storage.
-
__init__
(conn)[source]¶ Initializes a Docs.
Use
stardog.connection.Connection.docs()
instead of constructing manually.
-
add
(name, content)[source]¶ Adds a document to the store.
- Parameters
name (str) – Name of the document
content (Content) – Contents of the document
Examples
>>> docs.add('example', File('example.pdf'))
-
delete
(name)[source]¶ Deletes a document from the store.
- Parameters
name (str) – Name of the document
-
get
(name, stream=False, chunk_size=10240)[source]¶ Gets a document from the store.
- Parameters
name (str) – Name of the document
stream (bool) – If document should come in chunks or as a whole. Defaults to False
chunk_size (int) – Number of bytes to read per chunk when streaming. Defaults to 10240
- Returns
If stream=False
- Return type
str
- Returns
If stream=True
- Return type
gen
Examples
no streaming
>>> contents = docs.get('example')
streaming
>>> with docs.get('example', stream=True) as stream: contents = ''.join(stream)
-
-
class
stardog.connection.
GraphQL
(conn)[source]¶ Bases:
object
-
__init__
(conn)[source]¶ Initializes a GraphQL.
Use
stardog.connection.Connection.graphql()
instead of constructing manually.
-
add_schema
(name, content)[source]¶ Adds a schema to the database.
- Parameters
name (str) – Name of the schema
content (Content) – Schema data
Examples
>>> gql.add_schema('people', content=File('people.graphql'))
-
query
(query, variables=None)[source]¶ Executes a GraphQL query.
- Parameters
query (str) – GraphQL query
variables (dict, optional) – GraphQL variables. Keys: ‘@reasoning’ (bool) to enable reasoning, ‘@schema’ (str) to define schemas
- Returns
Query results
- Return type
dict
Examples
with schema and reasoning
>>> gql.query('{ Person {name} }', variables={'@reasoning': True, '@schema': 'people'})
with named variables
>>> gql.query( 'query getPerson($id: Integer) { Person(id: $id) {name} }', variables={'id': 1000})
-
remove_schema
(name)[source]¶ Removes a schema from the database.
- Parameters
name (str) – Name of the schema
-
-
class
stardog.connection.
ICV
(conn)[source]¶ Bases:
object
Integrity Constraint Validation.
-
__init__
(conn)[source]¶ Initializes an ICV.
Use
stardog.connection.Connection.icv()
instead of constructing manually.
-
add
(content)[source]¶ Adds integrity constraints to the database.
- Parameters
content (Content) – Data to add
Examples
>>> icv.add(File('constraints.ttl'))
-
convert
(content, graph_uri=None)[source]¶ Converts given integrity constraints to a SPARQL query.
- Parameters
content (Content) – Integrity constraints
graph_uri (str, optional) – Named graph from which to apply constraints
- Returns
SPARQL query
- Return type
str
Examples
>>> icv.convert(File('constraints.ttl'), graph_uri='urn:graph')
-
explain_violations
(content, graph_uri=None)[source]¶ Explains violations of the given integrity constraints.
- Parameters
content (Content) – Data to check for violations
graph_uri (str, optional) – Named graph from which to check for validations
- Returns
Integrity constraint violations
- Return type
dict
Examples
>>> icv.explain_violations(File('constraints.ttl'), graph_uri='urn:graph')
-
is_valid
(content, graph_uri=None)[source]¶ Checks if given integrity constraints are valid.
- Parameters
content (Content) – Data to check for validity
graph_uri (str, optional) – Named graph to check for validity
- Returns
Integrity constraint validity
- Return type
bool
Examples
>>> icv.is_valid(File('constraints.ttl'), graph_uri='urn:graph')
-
stardog.admin¶
Administer a Stardog server.
-
class
stardog.admin.
Admin
(endpoint=None, username=None, password=None)[source]¶ Bases:
object
Admin Connection.
This is the entry point for admin-related operations on a Stardog server.
-
__init__
(endpoint=None, username=None, password=None)[source]¶ Initializes an admin connection to a Stardog server.
- Parameters
endpoint (str, optional) – Url of the server endpoint. Defaults to http://localhost:5820
username (str, optional) – Username to use in the connection. Defaults to admin
password (str, optional) – Password to use in the connection. Defaults to admin
Examples
>>> admin = Admin(endpoint='http://localhost:9999', username='admin', password='admin')
-
database
(name)[source]¶ Retrieves an object representing a database.
- Parameters
name (str) – The database name
- Returns
The requested database
- Return type
-
databases
()[source]¶ Retrieves all databases.
- Returns
A list of database objects
- Return type
list[Database]
-
new_database
(name, options=None, *contents)[source]¶ Creates a new database.
- Parameters
- Returns
The database object
- Return type
Examples
Options
>>> admin.new_database('db', {'search.enabled': True})
bulk-load
>>> admin.new_database('db', {}, File('example.ttl'), File('test.rdf'))
bulk-load to named graph
>>> admin.new_database('db', {}, (File('test.rdf'), 'urn:context'))
-
new_role
(name)[source]¶ Creates a new role.
- Parameters
name (str) – The name of the new Role
- Returns
The new Role object
- Return type
-
new_stored_query
(name, query, options=None)[source]¶ Creates a new Stored Query.
- Parameters
name (str) – The name of the stored query
query (str) – The query text
options (dict, optional) – Additional options
- Returns
the new StoredQuery
- Return type
Examples
>>> admin.new_stored_query('all triples', 'select * where { ?s ?p ?o . }', { 'database': 'mydb' } )
-
new_user
(username, password, superuser=False)[source]¶ Creates a new user.
- Parameters
username (str) – The username
password (str) – The password
superuser (bool) – Should the user be super? Defaults to false.
- Returns
The new User object
- Return type
-
new_virtual_graph
(name, mappings, options)[source]¶ Creates a new Virtual Graph.
- Parameters
name (str) – The name of the virtual graph
mappings (Content) – New mapping contents
options (dict) – Options for the new virtual graph
- Returns
the new VirtualGraph
- Return type
Examples
>>> admin.new_virtual_graph( 'users', File('mappings.ttl'), {'jdbc.driver': 'com.mysql.jdbc.Driver'} )
-
queries
()[source]¶ Gets information about all running queries.
- Returns
Query information
- Return type
dict
-
query
(id)[source]¶ Gets information about a running query.
- Parameters
id (str) – Query ID
- Returns
Query information
- Return type
dict
-
restore
(from_path, *, name=None, force=False)[source]¶ Restore a database.
- Parameters
from_path (str) – the full path on the server to the backup
name (str, optional) – the name of the database to restore to if different from the backup
force (boolean, optional) – a backup will not be restored over an existing database of the same name; the force flag should be used to overwrite the database
Examples
>>> admin.restore("/data/stardog/.backup/db/2019-12-01") >>> admin.restore("/data/stardog/.backup/db/2019-11-05", name="db2", force=True)
-
role
(name)[source]¶ Retrieves an object representing a role.
- Parameters
name (str) – The name of the Role
- Returns
The Role object
- Return type
-
stored_queries
()[source]¶ Retrieves all stored queries.
- Returns
A list of StoredQuery objects
- Return type
list[StoredQuery]
-
stored_query
(name)[source]¶ Retrieves a Stored Query.
- Parameters
name (str) – The name of the Stored Query to retrieve
- Returns
The StoredQuery object
- Return type
-
user
(name)[source]¶ Retrieves an object representing a user.
- Parameters
name (str) – The name of the user
- Returns
The User object
- Return type
-
virtual_graph
(name)[source]¶ Retrieves a Virtual Graph.
- Parameters
name (str) – The name of the Virtual Graph to retrieve
- Returns
The VirtualGraph object
- Return type
-
virtual_graphs
()[source]¶ Retrieves all virtual graphs.
- Returns
A list of VirtualGraph objects
- Return type
list[VirtualGraph]
-
-
class
stardog.admin.
Database
(db)[source]¶ Bases:
object
Database Admin
-
__init__
(db)[source]¶ Initializes a Database.
Use
stardog.admin.Admin.database()
,stardog.admin.Admin.databases()
, orstardog.admin.Admin.new_database()
instead of constructing manually.
-
backup
(*, to=None)[source]¶ Backup a database.
- Parameters
to (string, optional) – specify a path on the server to store the backup
-
copy
(to)[source]¶ Makes a copy of this database under another name.
The database must be offline.
- Parameters
to (str) – Name of the new database to be created
- Returns
The new Database
- Return type
-
get_options
(*options)[source]¶ Gets database options.
- Parameters
*options (str) – Database option names
- Returns
Database options
- Return type
dict
- Examples
>>> db.get_options('search.enabled', 'spatial.enabled')
-
property
name
¶ The name of the database.
-
-
class
stardog.admin.
Role
(role)[source]¶ Bases:
object
-
__init__
(role)[source]¶ Initializes a Role.
Use
stardog.admin.Admin.role()
,stardog.admin.Admin.roles()
, orstardog.admin.Admin.new_role()
instead of constructing manually.
-
add_permission
(action, resource_type, resource)[source]¶ Adds a permission to the role.
- Parameters
action (str) – Action type (e.g., ‘read’, ‘write’)
resource_type (str) – Resource type (e.g., ‘user’, ‘db’)
resource (str) – Target resource (e.g., ‘username’, ‘*’)
Examples
>>> role.add_permission('read', 'user', 'username') >>> role.add_permission('write', '*', '*')
-
property
name
¶ The name of the Role.
-
remove_permission
(action, resource_type, resource)[source]¶ Removes a permission from the role.
- Parameters
action (str) – Action type (e.g., ‘read’, ‘write’)
resource_type (str) – Resource type (e.g., ‘user’, ‘db’)
resource (str) – Target resource (e.g., ‘username’, ‘*’)
Examples
>>> role.remove_permission('read', 'user', 'username') >>> role.remove_permission('write', '*', '*')
-
-
class
stardog.admin.
StoredQuery
(stored_query)[source]¶ Bases:
object
Stored Query
See also
https://www.stardog.com/docs/#_list_stored_queries https://www.stardog.com/docs/#_managing_stored_queries
-
__init__
(stored_query)[source]¶ Initializes a stored query.
Use
stardog.admin.Admin.stored_query()
,stardog.admin.Admin.stored_queries()
, orstardog.admin.Admin.new_stored_query()
instead of constructing manually.
-
property
creator
¶ The creator of the stored query.
-
property
database
¶ The database the stored query applies to.
-
property
description
¶ The description of the stored query.
-
property
name
¶ The name of the stored query.
-
property
query
¶ The text of the stored query.
-
property
reasoning
¶ The value of the reasoning property.
The value of the shared property.
-
-
class
stardog.admin.
User
(user)[source]¶ Bases:
object
-
__init__
(user)[source]¶ Initializes a User.
Use
stardog.admin.Admin.user()
,stardog.admin.Admin.users()
, orstardog.admin.Admin.new_user()
instead of constructing manually.
-
add_permission
(action, resource_type, resource)[source]¶ Add a permission to the user.
- Parameters
action (str) – Action type (e.g., ‘read’, ‘write’)
resource_type (str) – Resource type (e.g., ‘user’, ‘db’)
resource (str) – Target resource (e.g., ‘username’, ‘*’)
- Examples
>>> user.add_permission('read', 'user', 'username') >>> user.add_permission('write', '*', '*')
-
add_role
(role)[source]¶ Adds an existing role to the user.
- Parameters
role (str or Role) – The role to add or its name
Examples
>>> user.add_role('reader') >>> user.add_role(admin.role('reader'))
-
effective_permissions
()[source]¶ Gets the user’s effective permissions.
- Returns
User effective permissions
- Return type
dict
-
is_superuser
()[source]¶ Checks if the user is a super user.
- Returns
Superuser state
- Return type
bool
-
property
name
¶ The user name.
- Type
str
-
remove_permission
(action, resource_type, resource)[source]¶ Removes a permission from the user.
- Parameters
action (str) – Action type (e.g., ‘read’, ‘write’)
resource_type (str) – Resource type (e.g., ‘user’, ‘db’)
resource (str) – Target resource (e.g., ‘username’, ‘*’)
- Examples
>>> user.remove_permission('read', 'user', 'username') >>> user.remove_permission('write', '*', '*')
-
remove_role
(role)[source]¶ Removes a role from the user.
- Parameters
role (str or Role) – The role to remove or its name
- Examples
>>> user.remove_role('reader') >>> user.remove_role(admin.role('reader'))
-
-
class
stardog.admin.
VirtualGraph
(vg)[source]¶ Bases:
object
Virtual Graph
-
__init__
(vg)[source]¶ Initializes a virtual graph.
Use
stardog.admin.Admin.virtual_graph()
,stardog.admin.Admin.virtual_graphs()
, orstardog.admin.Admin.new_virtual_graph()
instead of constructing manually.
-
available
()[source]¶ Checks if the Virtual Graph is available.
- Returns
Availability state
- Return type
bool
-
mappings
(content_type='text/turtle')[source]¶ Gets the Virtual Graph mappings.
- Parameters
content_type (str) – Content type for results. Defaults to ‘text/turtle’
- Returns
Mappings in given content type
- Return type
str
-
property
name
¶ The name of the virtual graph.
-
stardog.content¶
Content that can be loaded into Stardog.
-
class
stardog.content.
File
(fname, content_type=None, content_encoding=None, name=None)[source]¶ Bases:
stardog.content.Content
File-based content.
-
__init__
(fname, content_type=None, content_encoding=None, name=None)[source]¶ Initializes a File object.
- Parameters
fname (str) – Filename
content_type (str, optional) – Content type. It will be automatically detected from the filename
content_encoding (str, optional) – Content encoding. It will be automatically detected from the filename
name (str, optional) – Object name. It will be automatically detected from the filename
Examples
>>> File('data.ttl') >>> File('data.doc', 'application/msword')
-
-
class
stardog.content.
Raw
(content, content_type=None, content_encoding=None, name=None)[source]¶ Bases:
stardog.content.Content
User-defined content.
-
__init__
(content, content_type=None, content_encoding=None, name=None)[source]¶ Initializes a Raw object.
- Parameters
content (obj) – Object representing the content (e.g., str, file)
content_type (str, optional) – Content type
content_encoding (str, optional) – Content encoding
name (str, optional) – Object name
Examples
>>> Raw(':luke a :Human', 'text/turtle', name='data.ttl') >>> Raw(open('data.ttl.zip', 'rb'), 'text/turtle', 'zip', 'data.ttl')
-
-
class
stardog.content.
URL
(url, content_type=None, content_encoding=None, name=None)[source]¶ Bases:
stardog.content.Content
Url-based content.
-
__init__
(url, content_type=None, content_encoding=None, name=None)[source]¶ Initializes a URL object.
- Parameters
url (str) – Url
content_type (str, optional) – Content type. It will be automatically detected from the url
content_encoding (str, optional) – Content encoding. It will be automatically detected from the filename
name (str, optional) – Object name. It will be automatically detected from the url
Examples
>>> URL('http://example.com/data.ttl') >>> URL('http://example.com/data.doc', 'application/msword')
-