Ontology Operations

Learn the fundamental operations for managing ontologies: uploading, waiting for processing, and retrieving details.

The full code for this example is available on GitHub.

This example covers the fundamental operations for managing ontologies, which are crucial for guiding the structure of your knowledge graphs. The workflow is very similar to file operations, involving uploading, waiting for processing, and retrieving details.

What You'll Learn

How to upload a local ontology file (e.g., a .ttl file) to the Perseus platform.
How to asynchronously wait for an ontology to be processed and validated.
How to find and retrieve ontology details using its unique ID.

Example Use Case: Setting Up Your Knowledge Schema

Before you build a graph, you often need to provide a schema or data model. In Perseus, this is done by uploading an ontology. This script demonstrates the essential first step of getting your ontology onto the platform and ensuring it's ready to be used in graph-building jobs.

Prerequisites

Before running this example, ensure you have followed the installation guide to set up your environment and obtain the necessary API keys.

Code Walkthrough

This walkthrough covers the three key stages of an ontology's lifecycle on the platform.

Uploading an Ontology

The process starts with perseus_client.upload_ontology(). This function takes the path to your local ontology file (e.g., in Turtle format) and uploads it to the Perseus API. It returns an Ontology object containing the unique id and the initial status.

import perseus_client
from perseus_client.models import OntologyStatus

# ... (inside a main function)

ontology_path = "assets/example_ontology.ttl"
print(f"Uploading ontology: {ontology_path}")

uploaded_ontology = perseus_client.upload_ontology(ontology_path)
print(f"Ontology upload initiated. ID: {uploaded_ontology.id}, Status: {uploaded_ontology.status}")

Waiting for the Ontology to be Processed

Just like files, ontologies are queued for server-side processing and validation after being uploaded. The perseus_client.wait_for_ontology_upload() function is a convenient helper that polls the API and waits until the ontology's status is UPLOADED, ensuring it's ready for use.

if uploaded_ontology.status == OntologyStatus.PENDING:
    print(f"Waiting for ontology {uploaded_ontology.id} to be processed...")
    processed_ontology = perseus_client.wait_for_ontology_upload(uploaded_ontology.id)
    print(f"Ontology processing complete. Final Status: {processed_ontology.status}")

Finding the Ontology

You can retrieve the details of any uploaded ontology using perseus_client.find_ontologies(). This function takes a list of ontology IDs and returns a list of Ontology objects with their full details.

print(f"Attempting to find the ontology with ID: {uploaded_ontology.id}")
found_ontologies = perseus_client.find_ontologies(ids=[uploaded_ontology.id])

if found_ontologies:
    print("Successfully found the ontology:")
    for o in found_ontologies:
        print(f"  - ID: {o.id}, Name: {o.name}, Status: {o.status}, Created At: {o.created_at}")
else:
    print(f"Could not find ontology with ID: {uploaded_ontology.id}")