The Importer

The Importer is the worker of the AutoGraph service. This page describes what it writes, how AutoGraph drives it, the cases in which you configure or call it yourself, and its HTTP API.

What the Importer builds

The Importer turns documents into a knowledge graph stored in your ArangoDB database. It chunks text, calls configured chat and embedding models, extracts entities and communities (in full GraphRAG mode), writes the graph data, and creates vector indexes where embeddings exist.

The resulting knowledge graph is the data layer your applications query with AutoRAG or with AQL directly.

In AutoGraph Studio, the Importer is the worker of the AutoGraph service: the orchestration starts Importer services, starts one import job per partition, monitors the jobs, and stops the services again. You configure the Importer, but you do not normally call it.

How AutoGraph runs the Importer

When you need to process large or heterogeneous document collections, AutoGraph manages the Importer for you. AutoGraph automatically discovers knowledge domains in your data, assigns the optimal RAG strategy (full_graphrag or vector_rag) per domain, and starts Importer services to build partitioned knowledge graphs.

In this mode, you do not call the Importer directly. AutoGraph handles starting the services, job submission, partition_id and rag_mode assignment, status polling, and teardown.

Three-layer architecture

AutoGraph organizes data across three layers. Each layer has a clear owner and purpose:

The Importer builds Layer 3 only. All Layer 3 collections carry a partition_id field so that data from different clusters coexists in the same collections.

For full details on Layers 1 and 2, see the AutoGraph Architecture documentation. For the Layer 3 collections and the asynchronous job lifecycle, see the Importer Architecture.

How AutoGraph starts import jobs

The same category label flows from files to clusters to strategies to Importer partitions:

1. You upload documents to the File Manager under the scope [project, category] (e.g., category "legal") and pass the labels in categories when you start the corpus build. The deprecated POST /v1/import-multiple endpoint takes the category in its module field instead.
2. AutoGraph’s corpus build clusters documents within each category using Leiden community detection.
3. The RAG strategizer analyzes each cluster and assigns either FullGraphRAG or VectorRAG.
4. Each assignment gets a rag_partition_id derived from the cluster key. For example, cluster cluster_legal_0 becomes legal_0_a (FullGraphRAG) or legal_0_b (VectorRAG).
5. Orchestration (POST /v1/orchestrate) starts Importer services and submits one import job per partition.
6. Each job payload includes partition_id (set to the rag_partition_id) and rag_mode (set to the assigned strategy).

flowchart LR
  module["`Category
    **legal**`"]

  module --> cluster0["cluster_legal_0"]
  module --> cluster1["cluster_legal_1"]
  module --> cluster2["cluster_legal_2"]

  cluster0 -->|full_graphrag| part0["`Partition
    **legal_0_a**`"]
  cluster1 -->|full_graphrag| part1["`Partition
    **legal_1_a**`"]
  cluster2 -->|vector_rag| part2["`Partition
    **legal_2_b**`"]

  part0 --> orch["Orchestration"]
  part1 --> orch
  part2 --> orch

  orch --> job0["Importer job 1"]
  orch --> job1["Importer job 2"]
  orch --> job2["Importer job 3"]

After the initial build, AutoGraph also uses the Importer for Incremental Graph Updates in Layer 3. It submits imports for new and changed files, and it can recluster a partition whose communities have drifted, but only if you ask for it. AutoGraph flags the drift and never reclusters on its own. Removing a document from Layer 3 is not an Importer call, AutoGraph handles it as part of its own delete and update operations. See Incremental Updates.

How partition_id maps to the Corpus Graph

• AutoGraph’s rag_partition_id (cluster key + strategy suffix _a/_b) is passed as partition_id in the import request payload.
• The Importer stores this value on every document, chunk, entity, community, and relation in the Knowledge Graph.
• Multiple partitions coexist in the same ArangoDB collections; filter by partition_id when querying.
• When inspecting Layer 3 data, the partition_id traces back to a specific Leiden cluster and its RAG strategy in the Corpus Graph.

When using the Importer standalone (without AutoGraph), you can set partition_id to any string to logically separate different import batches within the same collections. See the partition_id parameter reference for details.

RAG modes

The Importer supports two operational modes that determine how documents are processed and what knowledge-graph elements are created:

• Full GraphRAG (rag_mode: "full_graphrag", default): Extracts entities, relationships, and community structures to build a complete knowledge graph. Best for queries that require understanding relationships between concepts.
• Vector RAG (rag_mode: "vector_rag"): Faster processing using only document chunks and embeddings. Best for straightforward semantic search use cases that don’t need the full graph structure.

See Architecture for the collections each mode populates.

When you work with the Importer directly

Under normal operation you do not call the Importer; AutoGraph does. You still need its documentation in three situations:

• Tuning a build. The importer_env map of the orchestrate request passes environment variables to the Importer workers, such as chunk sizes, model names, and timeouts. Those keys are documented in Parameters and Limits and Quotas, and the provider settings in LLM Configuration.
• Reading the result. The collections, vector indexes, and job lifecycle are described in Architecture, and Inspect the Knowledge Graph shows how to verify an import and explore the collections. Semantic Units covers the images and web references the Importer extracts.
• Re-running a partition, or importing outside AutoGraph. The import endpoints accept single files and batches with full control over every parameter, for example to re-run one partition with custom settings. This path has no web interface: AutoGraph Studio only works with Context Graphs that belong to an AutoGraph project.

Prerequisites when you install it yourself

• Arango Contextual Data Platform with a valid Agentic AI Suite license.
• LLM and embedding API access (OpenAI-compatible endpoints).
• Valid JWT for the API (Authorization: Bearer ...).
• A project in the target database. Projects keep datasets and configurations isolated from each other. For instructions, see the Projects section in the Arango Control Plane (ACP) documentation.

To install and start an Importer service outside an orchestration, use the following endpoint of the Arango Control Plane (ACP), which manages the lifecycle of all AI services in the platform:

For detailed installation, monitoring, and lifecycle management instructions, see the Arango Control Plane (ACP) documentation. Supported input formats and the File Parser that converts them are described in Document conversion.

Authentication

All endpoints require a JWT in the Authorization header:

Authorization: Bearer <jwt_token>

The service handles token renewal automatically for long-running imports. Read-only endpoints (GET /v1/jobs and GET /v1/jobs/{job_id}) validate the token without renewing it.

Synchronous HTTP errors

These status codes apply to the immediate HTTP response of an API call:

Many business failures (busy importer, multi-file validation) return HTTP 200 with "success": false in the JSON body. See Error Handling for the full table.

Endpoints

Endpoints are served at http://<host>:8080. Through the platform’s API gateway, you reach them on port 8529 under /graphrag/importer/{serviceIdPostfix}/.

Call sequence

Via AutoGraph

When AutoGraph drives the pipeline, you do not call the Importer directly. AutoGraph orchestration submits one import per partition, sets partition_id from the corpus build, and sets rag_mode from the RAG Strategizer’s assignment. Monitor via the AutoGraph orchestration status and the platform service status. See How AutoGraph runs the Importer.

Reclustering

1. Call POST /v1/recluster and save the returned job_id.
2. Poll GET /v1/jobs/{job_id} until is_terminal is true.

See Incremental Updates for the request fields, what the operation rebuilds, and how to troubleshoot problems. To remove or replace a document, use AutoGraph’s POST /v1/graph/delete or POST /v1/graph/update.

Direct imports

The call sequences for importing a single file or a batch without AutoGraph are on the Import endpoints page.

Pages in this section

• LLM Configuration: Configure your chat and embedding providers (OpenAI-compatible APIs).
• Incremental Updates: Rebuild the community layer of a partition without importing the documents again, and how documents are removed and replaced in the knowledge graph.
• Inspect the Knowledge Graph: Check that an import succeeded and inspect the resulting collections.
• Architecture: Knowledge-graph collections, vector indexes, and the async-job lifecycle.
• Semantic Units: Process images and multimedia content.
• Import endpoints: Single-file and multi-file import requests, job monitoring, and sharding.
• Parameters: Complete request parameter reference.
• Limits and Quotas: Concurrency, size, timeout, and provider limits, and which of them are configurable.
• Error Handling: Troubleshooting, known limitations, and error markers in job status messages.

For the full machine-readable API, see the GraphRAG Importer API Reference .