On this page

Build and query a knowledge graph

Prepare and build a graph

  1. Use a managed storage binding on pgvector, Qdrant or Weaviate. ContextBase builds the graph from canonical chunks, so the source documents must be indexed in the space. The graph itself is stored in the platform’s PostgreSQL database.

  2. Configure a language model. Start with the graphrag preset or add the graph retriever to your pipeline. For a graph-only retriever use identity fusion. If you keep another retriever as well, select a fusion such as rrf. The preset uses ordinary grounded generation.

  3. Request a build with POST /api/v1/spaces/{space_id}/graph/rebuild from a caller authorized to configure the space. 202 Accepted means the work is queued. With neither a graph retriever nor a previous graph, the API returns 409. Poll GET /api/v1/spaces/{space_id}/graph/status.

  4. When state is built, try a question about one known entity and inspect the links to its sources. Record how it compares with passage search before increasing the corpus or changing settings.

The build extracts entities and relationships from chunks, groups related entities into communities and links them to source passages. It can call the model once per extracted chunk, plus additional calls for summaries and difficult entity matches. Start with a small, representative corpus, especially with a metered model. Source or build-setting changes can make a graph stale. Check status and rebuild. If only the entity-vector representation changed, the rebuild can re-embed existing entities.

Choose local or global use

  • Local. The graph retriever follows named entities and returns linked passages with graph context. Use it with the ordinary llm generator for questions such as “Which teams maintain line 4 and where are their responsibilities specified?”

  • Global. The graph_global generator uses community summaries. Use it for a question such as “What kinds of maintenance risks recur across our manuals?” It needs a graph retriever in the pipeline.

Build settings and source changes can make an existing graph stale. Review its status, then request a rebuild. A change limited to the entity-vector representation can be served by re-embedding existing entities instead of prompting the model about every chunk again.

Build request · Build implementation

Build settings

Set these on the graph retriever:

  • entity_types defaults to person, organization, location, event, concept and work. Focus this list on the types of entities your questions link together.

  • extraction_share=1.0 reads all eligible chunks with the model. Lower it to sample the most central fragments by dense-vector similarity. The platform can link unextracted chunks by the entities they name, but their text contributes no new entities or relationships.

  • build_model, build_api_base and build_temperature can override the space’s model for extraction, community summaries and model-assisted entity resolution. build_concurrency limits concurrent calls. If unset, it uses the installation ceiling.

  • clustering_resolution=1.0 controls grouping, with clustering_seed=0 by default. unlinked_group_size=32 groups entities with no relationships at the coarse level.

  • community_summary_source="at_build" writes summaries during the build. on_demand defers the work until they are needed. Compare build cost and question latency for your workload.

  • entity_resolution_normalize and entity_resolution_match_spellings default to true. The spelling threshold is entity_resolution_threshold=0.85. entity_resolution_match_vectors and entity_resolution_ask_model default to false. If you enable vector matching, the default threshold is entity_resolution_vector_threshold=0.95.

Local retrieval settings

The entity matcher defaults to entity_search_mode="words", with vectors or both available. For vector matching, choose entity_vector_text="name" (default) or name_and_description. A graph must have entity vectors built for the selected representation. A vector match must meet entity_search_threshold=0.75. entity_search_requires_description defaults to true. entity_top_k controls how many entities contribute their context. When unset, it follows the retrieval depth. The result count still counts passages.

The switches include_source_fragments, include_entity_context and include_community_summaries are on by default. community_summary_levels="base" is the default, with base_and_coarse available. context_budget caps the assembled context in characters and otherwise follows retrieval depth. fragment_context_share=0.5 and community_context_share=0.1 reserve room for passages and summaries. Their sum must be below 1 to leave room for entities and relationships.

Generate a global answer (graph_global)

After building the graph, set the generator to graph_global. This generator drafts partial answers from community summaries, rates their usefulness and synthesizes the survivors. It uses graph summaries as grounding. Consult source passages as well when checking a specific claim.

Use entry="level" (default) to start at the coarsest available level, or set level to choose the starting level. The generator can descend into finer communities in either case. Use entry="retrieval" to read the base communities of matched entities. It stays at the base level and requires a path without query transforms. If entity matching finds nothing, it returns no overview answer for that question.

{
  "node": "graph_global",
  "params": {"entry": "level", "map_top_k": 8, "map_budget": 32}
}
  • map_top_k=8 limits the best partial answers selected from the entire walk for the final synthesis. min_score=1 (0–100) is the minimum contribution score.

  • map_budget=64 is checked between levels in entry="level". It prevents further descent once reached. The generator always finishes the current level, so the actual count of evaluated summaries can exceed it. In entry="retrieval" the same value is a hard cap on readings of the matched communities, strongest matches first. One reading can be a full summary or a part of a large community.

  • map_concurrency limits simultaneous model calls for one question and defaults to the installation ceiling. model, api_base and temperature can override generation settings. If summaries are written on demand, community_summary_budget=16 on the retriever is the per-level summary budget for a global walk.

Requests with metadata_filter receive 409 on this generation path. To use document filters in the same space, call /search for passages from the retrieval pipeline. See Generate answers and inspect their sources for supported configurations.

Graph settings · Global generator

Inspect status and compare results

  • absent: check that the pipeline includes a graph retriever and request a build. building: wait for the worker.

  • stale: inspect outdated_settings, predating_settings and build_settings_known before rebuilding. Compare built_at with extracted_at to see whether the corpus was read again.

  • built with missing entities: check skipped_fragments (failed extractions) and unextracted_fragments (outside extraction coverage). The second count can be expected when extraction_share is less than 1.

  • Many isolated entities: inspect extracted_entities, resolved_entities, base_communities and mean_community_size. Try more appropriate entity types or resolution settings on a small sample before a larger rebuild.

  • Missing citations: review relations_without_sources and dropped_sources. Recut documents can replace the chunks that a graph had linked to. A graph description and its source passage are different pieces of evidence.

Compare local results on a fixed set of entity questions and global answers on overview questions. Record source coverage, representative errors, runtime and model cost beside any quality score. Keep a plain-retrieval baseline. See Evaluate retrieval and answers.

Graph status implementation

ContextBase0.1.0

Search the documentation