Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/neo4j-labs/neocarta/llms.txt

Use this file to discover all available pages before exploring further.

The OSI connector is Neocarta’s only bidirectional connector. It integrates with Open Semantic Interchange (OSI) — a YAML-based interchange format for semantic models. In the ingest direction, it reads an OSI YAML spec (from a local path or an HTTP(S) URL) and loads the full semantic model into Neo4j. In the export direction, it reads an OsiSemanticModel subgraph from Neo4j by name and emits a spec-compliant OSI YAML file. A ready-to-use 33-table sample lives at datasets/osi/acme_semantic_model.yaml, exercising metrics, joins with composite keys, and ai_context synonyms.

​
Import

from neocarta.connectors.osi import OsiConnector

​
Parameters

​
neo4j_driver
neo4j.Driver
required
Connected Neo4j driver instance.
​
database_name
str
default:"neo4j"
Target Neo4j database name.
​
http_timeout
float
default:"30.0"
Timeout in seconds when fetching an OSI spec by HTTP(S) URL.

​
Ingest Direction

Reads an OSI YAML spec and loads it into Neo4j as an OsiSemanticModel subgraph.

​
What It Ingests

Graph nodeDescription
OsiSemanticModel (:Domain subtype)Top-level container for the semantic model
OsiTable (:Table:OsiTable)Datasets with primary keys, unique keys, labels, and time-dimension flags
OsiColumn (:Column:OsiColumn)Fields with optional is_time_dimension tri-state
QueryDatasets whose source is a SQL query rather than a 3-part identifier
MetricGoverned metric definitions
ExpressionDialect-specific expression definitions linked to Metric nodes
JoinJoin definitions with ordered from_columns / to_columns for composite-key support
OsiAiContextAI context aspects, including synonyms that become BusinessTerm upserts
OsiCustomExtensionsCustom extension aspects with literal-block JSON
BusinessTermUpserted (MERGE on name) from ai_context.synonyms
OSI-specific node labels are secondary labels layered on top of the primary label. An OsiTable is stored as (:Table:OsiTable), so graph traversals over (:Table) reach OSI-ingested data the same as data from any other connector.
dataset.source must be either a 3-part database.schema.table identifier or a SQL query string. 1-part and 2-part sources raise ValueError to surface spec-non-compliant input early.

​
ingest() Parameters

​
spec_source
str | Path
required
A local filesystem path or an http(s):// URL pointing to the OSI YAML spec.
​
version
str
default:"0.1.1"
Declared OSI spec version. Emits UnsupportedOsiVersionWarning if outside SUPPORTED_VERSIONS ("0.1.1") or if the parsed spec’s version field is missing or mismatched.

​
Code Example

import os
from pathlib import Path
from dotenv import load_dotenv
from neo4j import GraphDatabase
from neocarta.connectors.osi import OsiConnector

load_dotenv()

neo4j_driver = GraphDatabase.driver(
    uri=os.getenv("NEO4J_URI"),
    auth=(os.getenv("NEO4J_USERNAME"), os.getenv("NEO4J_PASSWORD")),
)
neo4j_database = os.getenv("NEO4J_DATABASE", "neo4j")

connector = OsiConnector(neo4j_driver=neo4j_driver, database_name=neo4j_database)

# Ingest from a local file (the ACME sample dataset)
connector.ingest(
    spec_source=Path("datasets/osi/acme_semantic_model.yaml"),
    version="0.1.1",
)

# Or ingest directly from an HTTP(S) URL
connector.ingest(
    spec_source="https://raw.githubusercontent.com/open-semantic-interchange/OSI/osi-0.1.1-rc1/examples/tpcds_semantic_model.yaml",
    version="0.1.1",
)

neo4j_driver.close()

​
CLI

pip install "neocarta[cli]"

neocarta osi ingest \
  --spec-source ./datasets/osi/acme_semantic_model.yaml

# From a remote URL:
neocarta osi ingest \
  --spec-source "https://raw.githubusercontent.com/open-semantic-interchange/OSI/osi-0.1.1-rc1/examples/tpcds_semantic_model.yaml"

​
Export Direction

Reads an OsiSemanticModel subgraph from Neo4j by name and emits a spec-compliant OSI YAML file. The connector emits whatever osi_version was stored on the OsiSemanticModel node at ingest time — there is no export-side version argument.

​
What It Exports

  • Full OsiSemanticModel subgraph filtered by semantic_model_name
  • Preserved column ordering and primary/unique key lists in flow style (primary_key: [a, b])
  • Native YAML structure for ai_context (not a quoted JSON string)
  • Literal-block JSON (|) for custom_extensions[].data

​
export() Parameters

​
semantic_model_name
str
required
The name property of the :OsiSemanticModel node to export.
​
output_path
str | Path
required
Destination filesystem path for the OSI YAML output.

​
Code Example

# (continuing from the ingest example above, or a new connector instance)
connector = OsiConnector(neo4j_driver=neo4j_driver, database_name=neo4j_database)

connector.export(
    semantic_model_name="acme_corp_model",
    output_path=Path("acme_export.yaml"),
)
print("OSI YAML exported successfully!")

​
CLI

neocarta osi export \
  --semantic-model-name acme_corp_model \
  --output-path acme.yaml

​
Full Round-Trip Example

from pathlib import Path
from neo4j import GraphDatabase
from neocarta.connectors.osi import OsiConnector

driver = GraphDatabase.driver("bolt://localhost:7687", auth=("neo4j", "password"))
connector = OsiConnector(neo4j_driver=driver, database_name="neo4j")

# Ingest the ACME sample
connector.ingest(Path("datasets/osi/acme_semantic_model.yaml"), version="0.1.1")

# Export it back out
connector.export(
    semantic_model_name="acme_corp_model",
    output_path=Path("acme_export.yaml"),
)

driver.close()

​
Required Environment Variables

VariablePurpose
NEO4J_URINeo4j connection URI
NEO4J_USERNAMENeo4j username
NEO4J_PASSWORDNeo4j password
NEO4J_DATABASETarget Neo4j database (default: neo4j)

​
Synonyms and BusinessTerms

When a field, table, or column carries ai_context: {synonyms: [...]}, each synonym is upserted as a BusinessTerm node (MERGE on name) and linked via TAGGED_WITH. Because the MERGE uses name as the key, synonyms collide cleanly with catalog-derived business terms from connectors like Dataplex — pre-existing nodes keep their original id and properties.

​
Version Handling

The connector targets OSI spec version 0.1.1 (OsiConnector.SUPPORTED_VERSIONS). The version argument on ingest() is a per-call compatibility check — a single connector instance can ingest multiple files at different versions. An UnsupportedOsiVersionWarning is emitted (not raised) when the version is outside the supported set or mismatches the parsed spec, so ingest always proceeds. To silence the warning explicitly: 
import warnings
from neocarta.warnings import UnsupportedOsiVersionWarning

warnings.filterwarnings("ignore", category=UnsupportedOsiVersionWarning)

Build docs developers (and LLMs) love

Get started for freeTalk to us