Implementation:Run llama Llama index SQLTableNodeMapping

Overview

The SQLTableNodeMapping module provides the object-to-node mapping for SQL database tables in LlamaIndex. It defines a lightweight schema representation (SQLTableSchema) and a mapping class (SQLTableNodeMapping) that converts SQL table metadata into index-compatible TextNode instances. This module is located at llama-index-core/llama_index/core/objects/table_node_mapping.py (98 lines).

Purpose

This module enables SQL tables to participate in the ObjectIndex system. By converting SQL table schemas into text nodes, tables can be indexed and retrieved using vector similarity or other retrieval strategies. This is a core component of LlamaIndex's text-to-SQL pipeline, where the system first identifies relevant tables before generating SQL queries.

Key Components

Class: SQLTableSchema

A lightweight Pydantic model representing a SQL table with optional contextual information.

Field	Type	Description
table_name	str	The name of the SQL table.
context_str	Optional[str]	Optional human-readable context or description for the table. Defaults to None.

Class: SQLTableNodeMapping

A concrete implementation of BaseObjectNodeMapping[SQLTableSchema] that maps SQL table schemas to text nodes using live database metadata.

Constructor

def __init__(self, sql_database: SQLDatabase) -> None

Accepts an SQLDatabase instance which provides access to table metadata and schema information.

Method Implementations

Method	Description
from_objects	Class method requiring a sql_database keyword argument. Ignores the objs parameter since the mapping is built from the database connection. Raises ValueError if sql_database is not provided.
_add_object	Raises NotImplementedError. SQL table mappings are read-only from the database and do not support dynamic object addition.
to_node	Converts a SQLTableSchema into a TextNode. Constructs the text content from the table schema (via sql_database.get_single_table_info()) and optional context string. Uses uuid5 for deterministic node IDs.
_from_node	Reconstructs a SQLTableSchema from a node's metadata dictionary. Extracts table_name from metadata["name"] and context_str from metadata.get("context").
obj_node_mapping	Raises NotImplementedError. No in-memory mapping dictionary is maintained.
persist	Raises NotImplementedError. SQL table mappings are ephemeral and depend on a live database connection.
from_persist_dir	Raises NotImplementedError with an explicit message that this mapping does not support persistence.

Node Construction Details

The to_node method builds a TextNode with the following structure:

Component	Value
Node ID	uuid5(NAMESPACE_DNS, "{table_name}{context_str}") -- deterministic based on table name and context.
Text content	Schema information from the database (get_single_table_info), optionally followed by context string.
Metadata	{"name": table_name} and optionally {"context": context_str}.
Excluded metadata keys	Both "name" and "context" are excluded from embedding and LLM metadata to avoid redundancy with the text content.

The text content is formatted as:

Schema of table {table_name}:
{database_schema_info}
Context of table {table_name}:
{context_str}

The context section is only included when context_str is not None.

Dependencies

Module	Items Imported
uuid	uuid.uuid5 and uuid.NAMESPACE_DNS for deterministic node ID generation.
llama_index.core.bridge.pydantic	BaseModel for SQLTableSchema.
llama_index.core.objects.base_node_mapping	DEFAULT_PERSIST_DIR, DEFAULT_PERSIST_FNAME, BaseObjectNodeMapping.
llama_index.core.schema	BaseNode, TextNode.
llama_index.core.utilities.sql_wrapper	SQLDatabase for accessing table schema information.

Design Notes

• This mapping is read-only: objects cannot be added dynamically (_add_object raises NotImplementedError) and the mapping cannot be persisted.
• The mapping depends on a live SQLDatabase connection, making it inherently ephemeral. The database itself serves as the source of truth.
• Deterministic UUIDs (uuid5) ensure that the same table with the same context always produces the same node ID, enabling stable index behavior across rebuilds.
• Metadata keys are excluded from both embedding and LLM contexts to prevent the structured metadata from interfering with semantic search or prompt construction.