semantica/docs/reference/export.md

title, description, icon

title	description	icon
Export Module	Export knowledge graphs to RDF, Parquet, LPG, ArangoDB AQL, CSV, GraphML, OWL, JSON-LD, Arrow, and vector formats.	file-export

semantica.export serializes knowledge graphs to every downstream format:

• RDF: Turtle, JSON-LD, N-Triples, RDF/XML: with optional W3C PROV-O provenance inline
• Analytics: Apache Parquet and Arrow for Spark, BigQuery, Databricks
• Graph databases: Cypher CREATE statements for Neo4j; AQL INSERT for ArangoDB
• Standard formats: GraphML, GEXF, Graphviz DOT, CSV, OWL 2.0
• Vector export: NumPy .npz, FAISS index, binary for embedding pipelines

Exported Classes

Class	Output formats	Notes
RDFExporter	Turtle, JSON-LD, N-Triples, RDF/XML	export_to_rdf() → string; export() → file
ParquetExporter	.parquet	Requires pyarrow; explicit typed schema
LPGExporter	Cypher CREATE	Neo4j and Memgraph compatible
ArangoAQLExporter	AQL INSERT	Vertex and edge collections
GraphExporter	GraphML, GEXF, Graphviz DOT	Standard graph interchange formats
OWLExporter	OWL 2.0 in Turtle/XML	Ontology serialization
CSVExporter	.csv	export_entities() and export_relationships()
VectorExporter	JSON, NumPy .npz, FAISS index, binary	Embedding vector export
ArrowExporter	Apache Arrow IPC	Requires pyarrow; zero-copy transfer
DistanceExporter	CSV, JSONL	Pairwise distance metrics; takes a graph arg
ReportGenerator	HTML, Markdown, JSON, plain text	Analytics reports
NamespaceManager	:	RDF namespace extraction and declaration generation

Getting Started

from semantica.export import RDFExporter

# Export a knowledge graph dict to Turtle
exporter = RDFExporter()
rdf_str = exporter.export_to_rdf(graph, format="turtle")
with open("output.ttl", "w") as f:
    f.write(rdf_str)

Or use the one-liner convenience functions:

from semantica.export import export_rdf, export_csv, export_lpg

export_rdf(graph,  "output.ttl",    format="turtle")
export_csv(graph,  "output_base")   # writes entities and relationships as CSV
export_lpg(graph,  "import.cypher", method="cypher")

Quick Export

```python from semantica.export import RDFExporter

exporter = RDFExporter()
rdf_str = exporter.export_to_rdf(graph, format="turtle")
```

```python exporter.export(graph, "output.ttl", format="turtle") ``` ```python from semantica.export import ParquetExporter

exporter = ParquetExporter(compression="snappy")
exporter.export_entities(entities, "nodes.parquet")
exporter.export_relationships(relationships, "edges.parquet")
```

```python from semantica.export import LPGExporter

exporter = LPGExporter()
exporter.export(graph, "import.cypher")   # Cypher CREATE statements
```

Exporters

Export to W3C RDF formats: Turtle, JSON-LD, N-Triples, and RDF/XML.

**`export_to_rdf()` returns a string; `export()` writes to a file:**

```python
from semantica.export import RDFExporter

exporter = RDFExporter()

# Returns RDF string
turtle_str  = exporter.export_to_rdf(graph, format="turtle")   # Turtle
jsonld_str  = exporter.export_to_rdf(graph, format="jsonld")   # JSON-LD
nt_str      = exporter.export_to_rdf(graph, format="ntriples") # N-Triples
xml_str     = exporter.export_to_rdf(graph, format="rdfxml")   # RDF/XML

# Accepted format aliases: "ttl" -> turtle, "nt" -> ntriples, "xml" -> rdfxml,
# "json-ld" -> jsonld, "rdf" -> rdfxml

# Write directly to file
exporter.export(graph, "output.ttl", format="turtle")

# Also available
exporter.export_knowledge_graph(graph, "output.ttl", format="turtle")
```

<Warning>
  **`export_to_rdf()` returns a string: it does not write a file.** Call `export()` or `export_knowledge_graph()` to write directly to disk.
</Warning>

<Tip>
  **Use `export_to_rdf()` + string for inspection, `export()` for production.** In notebooks or debug sessions, `export_to_rdf()` is handy for quick inspection. For CI pipelines and pipelines writing files, `export()` is a single call.
</Tip>

<Tip>
  **Use `turtle` for human readability, `ntriples` for streaming.** Turtle is compact and readable for debugging and sharing. N-Triples (`.nt`) is line-oriented: one triple per line: making it safe to stream, concatenate, and process with standard Unix tools.
</Tip>

**Namespace management:**

```python
from semantica.export import NamespaceManager, RDFExporter

ns_manager = NamespaceManager()
# ns_manager.namespaces contains the built-in prefix dict (rdf, rdfs, owl, xsd, semantica)
# Add custom namespaces by updating the dict directly
ns_manager.namespaces["ex"]     = "http://example.org/"
ns_manager.namespaces["schema"] = "https://schema.org/"

# Generate Turtle prefix declarations
decls = ns_manager.generate_namespace_declarations(
    ns_manager.namespaces, format="turtle"
)
print(decls)   # @prefix ex: <http://example.org/> .   etc.
```

**Temporal export (OWL-Time):**

```python
# Pass include_temporal=True to embed OWL-Time interval triples
turtle_str = exporter.export_to_rdf(
    graph,
    format="turtle",
    include_temporal=True,
    time_axis="valid",  # "valid" | "transaction" | "both"
)
```

```python from semantica.export import ParquetExporter

exporter = ParquetExporter(compression="snappy")
# compression: snappy | gzip | brotli | zstd | lz4 | none

# Export entities and relationships as separate Parquet files
exporter.export_entities(entities,           "nodes.parquet")
exporter.export_relationships(relationships, "edges.parquet")

# Export full knowledge graph (writes entities.parquet and relationships.parquet)
exporter.export_knowledge_graph(graph, "output_base")
# → output_base_entities.parquet, output_base_relationships.parquet

# Generic export from list or dict
exporter.export(entities, "entities.parquet")
exporter.export(graph,    "output_base")
```

<Warning>
  **`ParquetExporter` and `ArrowExporter` require `pyarrow`.** Both fall back to a no-op stub class if `pyarrow` is not installed. Install with `pip install pyarrow` before using these exporters.
</Warning>

<Tip>
  **Use `ParquetExporter` for downstream analytics.** Parquet preserves column types (int, float, datetime) that CSV loses and is natively supported by Spark, BigQuery, Databricks, and Snowflake. Use `compression="snappy"` for a good balance of speed and compression.
</Tip>

Requires `pyarrow`: `pip install pyarrow`. Schema is explicitly typed.

```python
from semantica.export import CSVExporter

exporter = CSVExporter(delimiter=",")
exporter.export_entities(entities,           "nodes.csv")
exporter.export_relationships(relationships, "edges.csv")
exporter.export_knowledge_graph(graph,       "output_base")
```

```python
from semantica.export import SemanticNetworkYAMLExporter

exporter = SemanticNetworkYAMLExporter()
exporter.export(graph, "graph.yaml")
```

The YAML exporters read `entities`/`relationships`/`triplets` (with
`nodes`/`edges` accepted as aliases, so `ContextGraph.to_dict()` exports
directly). A non-empty mapping supplying none of them raises
`ValidationError` rather than writing a file with every collection empty,
as does one whose collection value is not a list of records
(`{"entities": "abc"}`).

**LPGExporter** writes Cypher `CREATE` statements for Neo4j and Memgraph:

```python
from semantica.export import LPGExporter

exporter = LPGExporter()

# Write Cypher CREATE statements to file
exporter.export(graph, "import.cypher")

# Also available
exporter.export_knowledge_graph(graph, "import.cypher")
```

**ArangoAQLExporter** writes `INSERT` statements for ArangoDB:

```python
from semantica.export import ArangoAQLExporter

exporter = ArangoAQLExporter(
    vertex_collection="entities",
    edge_collection="relationships"
)

# Write AQL INSERT statements to file
exporter.export(graph, "import.aql")
exporter.export_knowledge_graph(graph, "import.aql")
```

Both exporters write to a file and return `None`.

`LPGExporter`, `ArangoAQLExporter`, and `Neo4jCSVExporter` resolve mapping
payloads on the same terms as the YAML exporters above, so an unrecognized
or malformed mapping is rejected instead of exported as an empty graph.
`Neo4jCSVExporter` still reads graph *objects* off their
`nodes`/`entities` and `edges`/`relationships` attributes.

<Warning>
  **`ArangoAQLExporter.export()` and `LPGExporter.export()` write to a file and return `None`.** They do not return the AQL/Cypher string. Write to a file and read it back if you need the string.
</Warning>

```python from semantica.export import GraphExporter

exporter = GraphExporter()
exporter.export(graph, "graph.graphml", format="graphml")  # Gephi, yEd
exporter.export(graph, "graph.gexf",    format="gexf")     # Gephi streaming
exporter.export(graph, "graph.dot",     format="dot")      # Graphviz
```

```python
from semantica.export import OWLExporter

exporter = OWLExporter()
exporter.export(ontology, path="ontology.owl", format="owl-xml")
exporter.export(ontology, path="ontology.ttl", format="turtle")
```

**VectorExporter**: takes `(vectors, file_path, format=)`:

```python
from semantica.export import VectorExporter

exporter = VectorExporter()
# vectors: list of dicts with 'id', 'vector', 'text', 'metadata' keys
exporter.export(vectors, "vectors.json",  format="json")
exporter.export(vectors, "vectors.npz",   format="numpy")   # NumPy .npz
exporter.export(vectors, "vectors.bin",   format="binary")
exporter.export(vectors, "vectors.faiss", format="faiss")
```

**ArrowExporter**: requires `pyarrow`:

```python
from semantica.export import ArrowExporter

exporter = ArrowExporter()
exporter.export(graph, "graph.arrow")
```

**DistanceExporter**: takes a `graph` argument at construction:

```python
from semantica.export import DistanceExporter

exporter = DistanceExporter(graph)   # graph is required

# Compute all pairwise distances and write to file
exporter.to_csv("distances.csv")
exporter.to_jsonl("distances.jsonl")

# Compute with column selection and optional node subset
exporter.to_csv(
    "distances.csv",
    include=["source_id", "target_id", "hop_count", "distance_band"],
    node_subset=["node_a", "node_b", "node_c"],
)

# Return as pandas DataFrame (requires pandas)
df = exporter.to_dataframe(include=["hop_count", "semantic_similarity"])

# Return as string (for API responses)
csv_str  = exporter.to_csv_string(node_subset=["node_a", "node_b"])
jsonl_str = exporter.to_jsonl_string()
```

Available `include` columns: `source_id`, `source_type`, `target_id`, `target_type`, `hop_count`, `weighted_distance`, `semantic_similarity`, `distance_band`, `source_betweenness`, `target_betweenness`.

<Warning>
  **`DistanceExporter` requires a graph at construction.** Instantiate as `DistanceExporter(graph)`, not `DistanceExporter()`. Semantic similarity columns (`semantic_similarity`) require the graph nodes to have embeddings in their properties.
</Warning>

**ReportGenerator:**

```python
from semantica.export import ReportGenerator

generator = ReportGenerator()
generator.generate_report(data, "report.html",  format="html")
generator.generate_report(data, "report.md",    format="markdown")
generator.generate_report(data, "report.json",  format="json")
generator.generate_report(data, "report.txt",   format="text")
```

Convenience Functions

from semantica.export import (
    export_rdf, export_json, export_parquet, export_csv,
    export_lpg, export_arango, export_graph, export_owl,
    export_vector, export_arrow, export_yaml, generate_report,
)

export_rdf(graph,     "output.ttl",    format="turtle")
export_rdf(graph,     "output.nt",     format="ntriples")
export_json(graph,    "output.json",   format="json")
export_parquet(graph, "output_base",   compression="snappy")
export_csv(graph,     "output_base")   # uses CSVExporter.export()
export_lpg(graph,     "import.cypher", method="cypher")
export_arango(graph,  "import.aql")
export_graph(graph,   "graph.graphml", format="graphml")
export_owl(ontology,  "ontology.owl",  format="owl-xml")
export_vector(vectors,"vectors.json",  format="json")
export_arrow(graph,   "graph.arrow")
export_yaml(graph,    "graph.yaml",    method="semantic_network")
generate_report(data, "report.html",   format="html")

The export_csv convenience function delegates to CSVExporter.export(). For per-type exports use the class directly (exporter.export_entities(), exporter.export_relationships()).

Format Reference

Format string	Canonical name	Exporter	File ext	Best for
"turtle" / "ttl"	turtle	RDFExporter	.ttl	Readable RDF, ontology sharing
"jsonld" / "json-ld"	jsonld	RDFExporter	.jsonld	APIs, Linked Data, JSON pipelines
"ntriples" / "nt"	ntriples	RDFExporter	.nt	Streaming RDF, line-by-line processing
"rdfxml" / "xml" / "rdf"	rdfxml	RDFExporter	.rdf	W3C RDF/XML, broadest compatibility
"parquet"	parquet	ParquetExporter	.parquet	Spark, BigQuery, Databricks, Snowflake
"cypher"	cypher	LPGExporter	.cypher	Neo4j, Memgraph import
"aql"	aql	ArangoAQLExporter	.aql	ArangoDB vertex + edge collections
"graphml"	graphml	GraphExporter	.graphml	Gephi, yEd visualization
"gexf"	gexf	GraphExporter	.gexf	Gephi streaming format
"dot"	dot	GraphExporter	.dot	Graphviz rendering
"owl-xml"	owl-xml	OWLExporter	.owl	OWL 2.0 ontology distribution
"csv"	csv	CSVExporter	.csv	Spreadsheets, simple pipelines
"yaml"	yaml	SemanticNetworkYAMLExporter	.yaml	Human-readable config-driven use
"arrow"	arrow	ArrowExporter	.arrow	Zero-copy inter-process transfer
"json"	json	VectorExporter	.json	Vector embeddings
"numpy"	numpy	VectorExporter	.npz	NumPy arrays from embeddings
"binary"	binary	VectorExporter	.bin	Raw float32 binary
"faiss"	faiss	VectorExporter	.faiss	Direct FAISS index files
"html" / "markdown" / "json" / "text"	:	ReportGenerator	.html / .md / .json / .txt	Analytics reports

**Match your export format to your consumer.** Neo4j → `cypher`; ArangoDB → `aql`; Gephi/yEd → `graphml` or `gexf`; semantic web tools → `turtle` or `json-ld`; analytics pipelines → `parquet`; zero-copy IPC → `arrow`.

• Triplet Store — Store RDF exports in a SPARQL-queryable backend.
• Ontology — Export OWL ontologies.
• Provenance — Include provenance metadata in RDF exports.
• Pipeline — Add export as a final pipeline step.