Examples

All the following examples use the Client class, set up as follows:

from datagraphs import Client

client = Client(
    project_name="my-project",
    api_key="bZiDs4.....",
    client_id="sR5dfR.....",
    client_secret="pRM6kR....."
)

Querying data

The query method supports filtering, faceting, sorting, and pagination.

# Simple query — fetch all entities
results = client.query()

# Filter by type
results = client.query(filters="type:Person")

# Free-text search
results = client.query(q="searchTerm")

# Pagination
results = client.query(page_size=20, page_no=2)

# Sorting
results = client.query(sort="label:asc")

# Faceted search — returns (results, facets) tuple
results, facets = client.query(facets="type")

For full query reference, see client.query().

Retrieving all entities of a type

The get method automatically paginates through all results for a given class.

# Fetch all Person entities
people = client.get("Person")

# Include date metadata
people = client.get("Person", include_date_fields=True)

# Fetch in a specific language
people = client.get("Person", lang="en")

For more information, see client.get().

Loading data into a dataset

The put method loads entities into a dataset, automatically batching large payloads.

# Load a single entity
client.put("my-dataset", {"id": "urn:my-project:Person:1", "type": "Person", "label": "Alice"})

# Load multiple entities
entities = [
    {"id": "urn:my-project:Person:1", "type": "Person", "label": "Alice"},
    {"id": "urn:my-project:Person:2", "type": "Person", "label": "Bob"},
]
count = client.put("my-dataset", entities)
print(f"Loaded {count} entities")

For more information, see client.put().

Working with schemas

The Schema class lets you define and manipulate domain models programmatically.

from datagraphs import Client, Schema
from datagraphs.enums import DATATYPE

# Create a new schema
schema = Schema(name="My Model", version="1.0")

# Add a class
schema.create_class("Person", description="A person entity")

# Add properties
schema.create_property("Person", "email", DATATYPE.TEXT, description="Email address")
schema.create_property("Person", "age", DATATYPE.INTEGER, is_optional=True)

# Apply the schema to the project
client.apply_schema(schema)

# Retrieve the current schema
current = client.get_schema()

For the full Schema reference, see Schema.

Deploying a project with Gateway

The Gateway class provides a high-level interface for deploying schemas and datasets together.

from datagraphs import Client, Gateway, Schema, Dataset

client = Client(
    project_name="my-project",
    api_key="...",
    client_id="...",
    client_secret="..."
)
gateway = Gateway(client)

# Define schema and datasets
schema = Schema(name="My Model", version="1.0")
schema.create_class("Person")

datasets = [
    Dataset(name="People", project="my-project", classes=["Person"])
]

# Deploy the project
gateway.load_project(schema, datasets)

# Bulk load data from JSON files
stats = gateway.load_data(from_dir_path="./data")
print(f"Loaded: {stats['loaded']}, Skipped: {stats['skipped']}")

# Export data to disk
stats = gateway.dump_data(to_dir_path="./export")

For the full Gateway reference, see Gateway.