Knowledge Kits define the structure, data, and metadata for treating knowledge graphs in a "KG as Code" manner. Coupled with some simple tooling, they offer a standardized way to automate, version, and share graph deployments, making it easier to manage complex graph systems.
# set up your venv
$ python -m venv venv
# activate it
$ source venv/bin/activate
# install the package
$ pip install -e .$ mkdir mykit
$ cd mykit
$ kits init --name my-first-kit --group tutorial --version 1.0This creates a skeleton for your new Kit. Go into the kit.yaml file and update the metadata to describe your Kit. Copy in your own data and model, create a complete readme. Then you're ready to install.
Create a new environment file from the example.
$ cp .env.example .envNEVER COMMIT YOUR .env FILE TO VERSION CONTROL.
The default_target defines which target to use on the CLI when none is specified.
You must then define your targets, a target is a Stardog Endpoint. Targets have a name, which is used on the CLI to lieu of a server & credentials. They also have the server URL in addition to the credentials. The format for definining a target is [target name]_[property]=[value].
The only required property is server, which is the location of the Stardog endpoint:
my_endpoint_server="https://abc123.stardog.cloud:5820"You must also specify your credentials for the endpoint. If you have a Stardog Password File, you can omit credentials in your environment, the Kits CLI will use the password file.
To specify credentials in your environment, you use the properties username and password:
my_endpoint_username="the_username"
my_endpoint_password="the_password"$ kits install -t my_endpoint$ kits uninstall -t my_endpointThis specification defines the structure and elements used for describing the configuration of a Stardog Knowledge Graph using YAML. It supports configurations in a "knowledge graph as code" manner, enabling automation and versioning.
These top-level fields define the identity and basic setup of the Knowledge Kit.
- Type:
string - Description: The category or group under which the kit.
- Example:
group: tutorial
- Type:
string - Description: The name of the kit.
- Example:
name: music
- Type:
string - Description: The version of the kit, following semantic versioning.
- Example:
version: 1.0
- Type:
string - Description: A human readable label for the kit
- Example:
description: "SPARQL Tutorial: Music"
- Type:
string - Description: A detailed description of the kit.
- Example:
description: "SPARQL Tutorial: Music"
- Type:
map - Description: Database configuration options for installing the kit in a new database.
- Example:
options: database.name: kit-music search.enabled: true graph.aliases: true
- Type:
string - Description: The alias of the data graph. This is the union of all of your graphs to allow for easy use in Voicebox, Explorer, and Studio.
- Example:
alias: music_data
Defines the data that makes up the contents of the kit
- Type:
string - Description: The path to the data file. This is relative to the "root" of the kit; where
kit.yamlis stored. Mutually exclusive withsource. - Example:
file: data.ttl
- Type:
string - Description: Name of the data source. Mutually exclusive with
file. - Example:
source: my_databricks
- Type:
string - Description: The name for the Virtual Graph that is to be created. Should be used with
source - Example:
name: my_vg
- Type:
string - Description: The named graph that the data will be loaded into. If
graphis omitted, data will be stored in the default graph unless it is an RDF file that supports named graphs, such as Trig. In those cases, the data will be loaded into the same graphs as the file. This is only used forfiledata sources. - Example:
graph: "stardog-tutorial:music:music_data"
- Type:
string - Description: Path to SMS mapping file for enabling transformation from non RDF data sources. Can be used with static files (JSON, CSV) or can be used as a part of a virtual graph.
- Example:
mappings: mappings/characters.sms
This section defines the schemas associated with the knowledge kit.
- Type:
string - Description: The name of the schema.
- Example:
name: "music"
- Type:
array of strings - Description: A list of graph URIs that belong to the schema.
- Example:
graphs: - "stardog-tutorial:music:music_schema"
A collection of namespace definitions that can be used throughout the knowledge kit.
- Type:
map - Description: Define namespaces for shorthand references in the kit.
- Example:
namespaces: catalog: "tag:stardog:api:catalog:" m: "urn:stardog:modules:" kg: "tag:stardog:api:context:" sqs: "tag:stardog:api:sqs:"
For any of the data which uses mappings, a Stardog Data Source is required to create the virtual graph.
The value of the sources key is an array of data source descriptors. The name of the data source should match the exact name of
the source as defined in the data.
Here is an example data source definition:
- name: CentralDatabricks
options:
jdbc.driver: "com.simba.spark.jdbc.Driver"
jdbc.url : "jdbc:spark://example.cloud.databricks.com:443/default;transportMode=http;ssl=1;AuthMech=3;httpPath=/sql/1.0/endpoints/abcc123def456ghj789;UseNativeQuery=1"
jdbc.username: "token"
sql.schemas: "default"
testOnBorrow: true
validationQuery: "select 1"The valid options here correspond to the set of valid Data Source Configuration options.
Do NOT put these in your Kit. Kits belong in version control, but passwords do not.
To specify passwords for your data sources, you will need to update your .env file. The convention to follow when specifiying these credentials in your environment, is [source name]_password=mypassword. For the above data source descriptor example, we would specify the password as such:
CentralDatabricks_password="abc123"- Type:
string - Description: Path to a file containing stored queries for the knowledge graph.
- Example:
queries: "test_stored_queries.ttl"
Metadata associated with the knowledge graph project, including licensing, contributors, and tags. This information is not used by the Knowledge Kit tooling; it is intended for use by Kit creators.
- Type:
map - Description: License information for the project.
- Subfields:
name: License name (e.g., "Apache 2.0").link: Link to the full license text.
- Example:
license: name: "Apache 2 License" link: "https://www.apache.org/licenses/LICENSE-2.0"
Information when kits are published on Stardog Cloud.
- Type:
map - Description: Marketplace-related metadata for the knowledge kit.
- Subfields:
publisher: The publisher of the knowledge graph.contributor: List of contributors.status: Current status (e.g., "Published").icon: An icon representing the project.tags: A list of tags relevant to the graph.subject: The subject or category of the graph.type: The type of the graph (e.g., "Tutorial", "Demo").
- Example:
marketplace: publisher: sd:Stardog contributor: - sd:users:mike status: Published icon: "learning" tags: - SPARQL - Studio subject: - General type: - Tutorial initialSearch: "`http://stardog.com/tutorial/ABBA`"
- Type:
string - Description: The publisher of the knowledge kit.
- Example:
publisher: sd:Stardog
- Type:
array of strings - Description: List of contributors to the project.
- Example:
contributor: - sd:users:mike
- Type:
string - Description: The current status of the knowledge kit (e.g., "Published", "Draft", "Archive").
- Example:
status: Published
- Type:
string - Description: Icon used to represent the kit in interfaces.
- Example:
icon: "learning"
- Type:
string - Description: URI of the primary concept represented by the kit.
- Example:
primaryConcept: "http://stardog.com/tutorial/Band"
- Type:
string - Description: A SPARQL query or URI representing the initial search or focus of the knowledge kit.
- Example:
initialSearch: "`http://stardog.com/tutorial/ABBA`"
- Type:
string - Description: The database name associated with the kit.
- Example:
kitDb: "kit-starwars"