run-llama/llama_index · error · NotImplementedError

Not supported

Error message

Not supported

What it means

SQLStructStoreIndex.as_retriever() unconditionally raises NotImplementedError('Not supported'). A SQL index answers natural-language questions by generating and executing SQL, which is a query-engine flow, not a node-retrieval flow, so the BaseIndex retriever hook is deliberately disabled. There is no SQL retriever behind this index class; the code path exists only to satisfy the abstract interface.

Source

Thrown at llama-index-core/llama_index/core/indices/struct_store/sql.py:146

            for node_set in source_to_node.values():
                data_extractor.insert_datapoint_from_nodes(node_set)
        return index_struct

    def _insert(self, nodes: Sequence[BaseNode], **insert_kwargs: Any) -> None:
        """Insert a document."""
        data_extractor = SQLStructDatapointExtractor(
            Settings.llm,
            self.schema_extract_prompt,
            self.output_parser,
            self.sql_database,
            table_name=self._table_name,
            table=self._table,
            ref_doc_id_column=self._ref_doc_id_column,
        )
        data_extractor.insert_datapoint_from_nodes(nodes)

    def as_retriever(self, **kwargs: Any) -> BaseRetriever:
        raise NotImplementedError("Not supported")

    def as_query_engine(
        self,
        llm: Optional[LLMType] = None,
        query_mode: Union[str, SQLQueryMode] = SQLQueryMode.NL,
        **kwargs: Any,
    ) -> BaseQueryEngine:
        # NOTE: lazy import
        from llama_index.core.indices.struct_store.sql_query import (
            NLStructStoreQueryEngine,
            SQLStructStoreQueryEngine,
        )

        if query_mode == SQLQueryMode.NL:
            return NLStructStoreQueryEngine(self, **kwargs)
        elif query_mode == SQLQueryMode.SQL:
            return SQLStructStoreQueryEngine(self, **kwargs)
        else:

View on GitHub (pinned to afd0fef371)

Solutions

1. Use index.as_query_engine() instead — SQL indexes are consumed as query engines (NLStructStoreQueryEngine / SQLStructStoreQueryEngine).
2. If you need retrieval-style access to the underlying rows, query the SQLAlchemy engine directly or use the query engine's response metadata['sql_query'].
3. If generic code must branch, check isinstance(index, SQLStructStoreIndex) and route it to as_query_engine().

Example fix

# before
retriever = index.as_retriever()
query_engine = RetrieverQueryEngine(retriever)

# after
query_engine = index.as_query_engine()  # NLStructStoreQueryEngine
response = query_engine.query("How many cities are there?")

from llama_index.core.indices.struct_store.sql import SQLStructStoreIndex

def get_query_engine(index):
    if isinstance(index, SQLStructStoreIndex):
        return index.as_query_engine()  # never .as_retriever() on SQL indexes
    return index.as_query_engine()

from llama_index.core.indices.struct_store.sql import SQLStructStoreIndex

def supports_retriever(index) -> bool:
    return not isinstance(index, SQLStructStoreIndex)

try:
    retriever = index.as_retriever()
except NotImplementedError:
    retriever = None  # fall back to query engine for SQL-backed indexes
    engine = index.as_query_engine()

When it happens

Trigger: Calling index.as_retriever() on a SQLStructStoreIndex or GPTVectorStoreIndex alias user confusion; generic framework code that calls as_retriever() on any BaseIndex (e.g. routing code that treats all indexes uniformly); following retriever-based tutorials against a SQL index.

Common situations: Porting a VectorStoreIndex pipeline to SQL and keeping the retriever API; libraries that wrap any index with RetrieverQueryEngine(index.as_retriever()).

Related errors

• Unknown query mode: {query_mode}
• Unknown SQL parser mode: {sql_parser_mode}
• LLM must be a FunctionCallingLLM
• This query engine does not support retrieve, use query direc
• Unknown retriever mode: {retriever_mode}

AI-assisted analysis of run-llama/llama_index@afd0fef371 (2026-08-15). Data as JSON: /api/errors/43c0b92bc2c2d3f6. Report an issue: GitHub.