Neocarta: A Semantic Map for Enterprise Data

Neocarta is a Python library that builds a semantic layer in Neo4j. A semantic layer connects the structure of data with its business meaning. Agents use this graph through tools exposed by an MCP server. Neocarta supplies context. An agent and a separate database query tool use that context to answer questions. Neocarta is a Neo4j Labs project, with experimental status. It is not a supported Neo4j product.

Start with the missing connections. A schema may list an amount column, but the business definition tells the agent which amount the user means. A foreign key explains how that table relates to customers. Query history records how people have used those assets. An agent needs the structure, the meaning, and the links between them. That is the problem the metadata graph addresses.

Connectors read source metadata and convert it to a shared graph model. Neo4j stores entities and relationships, so facts from different sources can be retrieved together. Text indexes support search by words. Optional embeddings support search by meaning. Embeddings are generated after metadata has been loaded. The graph holds metadata and may include sampled values. This is not a copy of the source database. Choose which example values to load as part of configuring the connectors.

This slide moves from building the graph to using it. The graph contains metadata across the loaded sources. A retrieval tool returns a selected set of that metadata for the current question. That selected information is the context the agent works with. Search can start with a table, a column, or a metric. The available tools depend on the data and indexes in the graph. A useful answer may require several retrieval calls as the agent checks what it needs.

This simplified example shows why retrieval includes more than a table name. Types help the agent write valid comparisons. Examples help it choose a real status value. Foreign-key references provide known joins. References and values are optional. Their presence depends on the source and connector configuration. Missing keys still need investigation. This is context for writing a query; the agent must still build and check the query itself.

Use one question throughout this example. The agent asks Neocarta for the relevant context, then writes a query against the source database. The query tool and source system enforce their configured permissions. Query validation and answer citations must be provided by the surrounding application. Neocarta does not automatically add those controls. The local project includes a LangGraph example that connects Neocarta's MCP tools with a separate BigQuery execution tool. The exact number of retrieval calls depends on the question and the available metadata.

This illustrative path makes the graph concrete. A glossary term is linked to a column. That column belongs to a table. Another column on the same table carries a foreign-key reference to the customer table. The term mapping and foreign key must be loaded from a source or curated. They are stored facts for retrieval to follow. A missing relationship requires more source information or review. Search locates relevant entities and graph traversal supplies related details. Vector search and graph traversal work together in Neocarta.

Group connectors by the information they contribute. The source list belongs in the appendix so the main story stays focused on context. Schema connectors supply structure. Glossary sources supply terms and asset mappings. Open Semantic Interchange supplies models, formulas, and joins. Query log connectors record SQL and the assets that it uses. Query usage shows what was used. It does not by itself prove that a query or a join is correct for the current question.

Full-text search finds words in metadata. Vector search compares the meaning represented by embeddings. Hybrid search combines both. Business-term hybrid tools also use glossary tags when their required indexes and data are present. The retrieval queries traverse the graph after finding candidates. Vector search also returns structured context; it is not limited to a ranked list of names. Catalog browsing helps the agent orient itself.

The local MCP implementation supports metric search, metric expression retrieval, and retrieval of a complete OSI domain's context. These tools extend the story beyond table discovery. A saved definition gives the agent a formula to use. Approval and review of that formula are responsibilities of the team maintaining the model. The agent still has to apply the right date range, filters, and joins. OSI model tools are registered when the graph contains OSI model nodes. Metric search tools depend on the corresponding search indexes.

These are operating practices for the team building the application. Neocarta provides metadata ingestion and retrieval. A complete governance workflow also needs ownership, refresh processes, evaluation, and feedback. Source permissions and query validation belong in the query tool and database configuration. A connected graph still needs correct source information and expert review to remain useful over time.

Keep the status explicit. Query logs and their usage relationships exist today. The full process path described here is future work in this deck. Storing why a path was accepted or rejected could help later agents choose a useful starting point. A reused path must still be checked against the new question, current definitions, and current permissions.

Start with a question whose answer can be independently checked. Agree on what largest means, which date marks an order, and how the quarter is defined. Those decisions become terms, definitions, or test expectations. Load only the metadata needed for that workflow first. Check the links, connect retrieval and execution, and run the question end to end.

Close the main presentation with a concrete decision. A useful pilot shows whether connected metadata helps the agent select the correct data and produce a checked result at an acceptable time and cost. Use known answers and review failures. Expand after the team understands what worked and which metadata gaps remain. The local eval README marks the project's evaluation suite as work in progress. The next five slides are optional technical detail.

The connector list groups thirteen source connectors by their main job. CSV can also carry curated glossary and usage information. Databricks Tags loads governed-tag definitions. It is distinct from a glossary connector that links business terms to physical assets. OSI supports both ingestion and export. Embedding generation is a separate enrichment step after the source metadata has been loaded.

This is a simplified view of the model, with plain labels for readability. The core labels are Database, Schema, Table, Column, and Value. HAS_SCHEMA, HAS_TABLE, HAS_COLUMN, HAS_VALUE, and REFERENCES connect them. BusinessTerm nodes attach to tables or columns through TAGGED_WITH. Queries use USES_TABLE and USES_COLUMN relationships. OSI adds model, metric, expression, and join information to the shared graph. The picture groups extensions rather than showing every node and edge.

The server probes indexes and checks for BusinessTerm and OSI nodes. For each Table, Column, or Metric label, it registers the highest-priority search strategy whose prerequisites are met. Business-term hybrid search needs the label's text and vector indexes, the BusinessTerm full-text index, and BusinessTerm nodes. A schema vector tool is registered separately when its index is present. Catalog tools are always registered, though their results depend on graph contents. These checks select tools based on graph capabilities. Working credentials, provider configuration, and a running database are still required.

Embeddings support meaning-based search. Text search and catalog browsing can be used without embeddings. The enrichment reads descriptions, calls the configured embedding model, and writes vectors and indexes to Neo4j. Retrieval must use a compatible model and vector size. Reruns process nodes with missing embeddings. When a description changes, plan an explicit embedding refresh so the vector matches the new text.

The common connector design separates extraction, transformation, and loading. The connector class runs those components together. The shared model is the interface between ingestion and retrieval. Test both the source mapping and the context returned from the graph. Specialized metadata may need a model extension and corresponding tools.