🦙 LlamaIndex Vector Stores PolarDB-X
A powerful integration between LlamaIndex and PolarDB-X, enabling native vector search and SQL query capabilities for AI applications.
Overview
LlamaIndex PolarDB-X provides seamless integration between LlamaIndex, a framework for building context-augmented LLM applications, and PolarDB-X with native vector search support. This integration enables efficient vector storage and retrieval for AI applications like semantic search, recommendation systems, and RAG (Retrieval Augmented Generation).
PolarDB-X is a cloud-native distributed database system developed by Alibaba Cloud, featuring native HNSW-based vector index support that delivers high-performance approximate nearest neighbor (ANN) search directly within the database engine.
In addition to vector search, this package provides a PolarDBXSQLDatabase wrapper that enables LlamaIndex SQL query engines (e.g. NLSQLTableQueryEngine) to work seamlessly with PolarDB-X, and a create_partitioned_table helper for creating non-vector partitioned tables for distributed data scenarios.
Requirements
- Python 3.10+
- PolarDB-X with vector index support
- LlamaIndex core:
llama-index-core>=0.13.0,<0.15(included in package dependencies) - SQLAlchemy:
sqlalchemy>=2.0.0(included in package dependencies) - Async support:
aiomysql>=0.2.0(included in package dependencies) - MySQL driver:
pymysql>=1.0.0(included in package dependencies) - NumPy:
numpy>=1.24.0(included in package dependencies, required for MMR search)
Enable Vector Index
PolarDB-X disables the vector index feature by default (vidx_disabled = ON). You need to enable it before using this package:
-- Enable vector index (run as admin/root on DN node)
SET GLOBAL vidx_disabled = OFF;
This setting takes effect immediately for new connections. No restart required.
All transaction isolation levels (READ-COMMITTED, REPEATABLE-READ, SERIALIZABLE) are supported — choose according to your business needs.
Note: Some advanced features (e.g., inner product distance, index monitoring,
EF_CONSTRUCTIONparameter) require newer PolarDB-X versions. The package automatically detects available capabilities and adapts accordingly.
Features
- Native Vector Storage: Store embeddings using PolarDB-X's native
VECTOR(N)data type - HNSW Index: Efficient approximate nearest neighbor search with configurable
MandEF_CONSTRUCTIONparameters - Multiple Distance Metrics: Support for Cosine, Euclidean, and Inner Product distance (newer versions)
- Similarity Search: Perform efficient similarity searches with configurable top-k
- MMR Search: Maximal Marginal Relevance search for diverse results
- Metadata Filtering: Filter search results by metadata with rich operators (
$eq,$ne,$gt,$gte,$lt,$lte,$in,$nin) - Metadata-Based Operations: Search and delete nodes by metadata conditions without vector similarity
- Dynamic Index Management: Create, drop, and rebuild vector indexes at runtime without recreating tables
- Search Mode Control: Switch between ANN (index-accelerated) and KNN (full-scan) modes per query
- Per-Query Tuning: Adjust
ef_searchon a per-query basis for accuracy/latency trade-offs - Index Health Monitoring: Runtime statistics, index health diagnostics, and preload checks (newer versions)
- Batch Operations: Batch insert with UPSERT support within a single transaction
- Full Async Support: All public methods have async equivalents (
async_add,aquery, etc.) - Dual-Version Compatibility: Automatically detects database capabilities and adapts SQL accordingly
- Partitioned Table Support: Create partitioned vector tables with HASH/KEY/RANGE/LIST strategies, broadcast tables, and LOCALITY node assignment
- Custom Column Schema: Customize column names for all core fields (
id,node_id,text,embedding,metadata) and promote specific metadata keys to dedicated typed columns for faster filtering and indexing - Connection Pooling: Built-in SQLAlchemy Engine with connection pooling and automatic retry logic
- SQL Database Integration: Use PolarDB-X as a SQL database for LlamaIndex SQL agents with automatic DDL reflection compatibility (tab indentation, ENUM spacing, VECTOR type support)
Installation
pip install -U llama-index-vector-stores-polardbx
Optional Dependencies
For using OpenAI embeddings:
pip install llama-index-embeddings-openai
For using DashScope embeddings (Alibaba Cloud):
pip install llama-index-embeddings-dashscope
Quick Start
Basic Usage
from llama_index.vector_stores.polardbx import PolarDBXVectorStore
from llama_index.core import StorageContext, VectorStoreIndex, Settings
from llama_index.embeddings.openai import OpenAIEmbedding
# Configure embedding model
Settings.embed_model = OpenAIEmbedding()
# Create vector store
vector_store = PolarDBXVectorStore(
host="your-polardbx-host",
port=3306,
user="your-user",
password="your-password",
database="your-database",
table_name="my_vectors",
embed_dim=1536,
distance_strategy="cosine", # or "euclidean", "inner_product" (newer versions only)
)
# Create index from documents
storage_context = StorageContext.from_defaults(vector_store=vector_store)
index = VectorStoreIndex.from_documents(
documents,
storage_context=storage_context,
)
# Query
query_engine = index.as_query_engine()
response = query_engine.query("What is PolarDB-X?")
print(response)
Using from_params Factory Method
from llama_index.vector_stores.polardbx import PolarDBXVectorStore
vector_store = PolarDBXVectorStore.from_params(
host="your-polardbx-host",
port=3306,
user="your-user",
password="your-password",
database="your-database",
table_name="my_vectors",
embed_dim=1536,
distance_strategy="cosine",
ssl=True, # Enable TLS
ssl_ca="/path/to/ca.pem", # CA certificate
)
from_params accepts all the same parameters as the constructor, including custom column parameters (id_column, metadata_columns, etc.). See Configuration Options for the full list.
Using DashScope Embeddings
from llama_index.vector_stores.polardbx import PolarDBXVectorStore
from llama_index.core import Settings
from llama_index.embeddings.dashscope import DashScopeEmbedding
# Configure embedding model
Settings.embed_model = DashScopeEmbedding(
model_name="text-embedding-v4",
api_key="your-dashscope-api-key",
)
vector_store = PolarDBXVectorStore(
host="your-polardbx-host",
port=3306,
user="your-user",
password="your-password",
database="your-database",
table_name="my_vectors",
embed_dim=1024,
)
Custom Column Schema
By default, the vector store creates a table with five columns: id, node_id, text, metadata (JSON), and embedding (VECTOR). You can customize column names and promote specific metadata keys to dedicated typed columns for faster filtering and indexing.
Customizing Core Column Names
from llama_index.vector_stores.polardbx import PolarDBXVectorStore
vector_store = PolarDBXVectorStore(
host="your-host",
port=3306,
user="your-user",
password="your-password",
database="your-database",
table_name="my_vectors",
embed_dim=1536,
id_column="my_id", # default: "id"
node_id_column="my_node_id", # default: "node_id"
text_column="my_text", # default: "text"
embedding_column="my_embedding", # default: "embedding"
metadata_json_column="my_meta", # default: "metadata"; set None to disable
)
Promoting Metadata to Dedicated Columns
By default, all metadata is stored as a single JSON column. You can promote specific metadata keys to dedicated typed columns for faster filtering (direct column reference instead of JSON_EXTRACT) and native indexing.
Use Column objects when creating a new table (the data_type is included in DDL):
from llama_index.vector_stores.polardbx import PolarDBXVectorStore, Column
vector_store = PolarDBXVectorStore(
host="your-host",
port=3306,
user="your-user",
password="your-password",
database="your-database",
table_name="my_vectors",
embed_dim=1536,
metadata_columns=[
Column("category", "VARCHAR(64)", nullable=False),
Column("lang", "VARCHAR(8)"),
Column("price", "DECIMAL(10,2)"),
],
)
Use plain strings when connecting to an existing table (data type is ignored, taken from the existing schema):
vector_store = PolarDBXVectorStore(
host="your-host",
port=3306,
user="your-user",
password="your-password",
database="your-database",
table_name="existing_table",
embed_dim=1536,
perform_setup=False, # do not auto-create the table
metadata_columns=["category", "lang", "price"],
)
How Mapped Columns Work
When metadata columns are configured:
- On insert: Metadata keys matching mapped column names are extracted to their own columns. Remaining metadata keys (including LlamaIndex internal serialization data) are stored in the JSON column.
- On query: Mapped column values and JSON column values are merged into the metadata dict returned to LlamaIndex.
- On filter: Filters on mapped column keys use direct column references (
WHERE \category` = ?) for better performance. Filters on non-mapped keys useJSON_EXTRACT` on the JSON column.
No JSON Column Mode
Set metadata_json_column=None to store metadata exclusively in mapped columns, eliminating the JSON column entirely. This is useful for schemas where all metadata keys are known upfront.
vector_store = PolarDBXVectorStore(
...,
metadata_json_column=None,
metadata_columns=["category", "lang"],
)
Note: When
metadata_json_column=None, filtering on a metadata key that is not a mapped column raisesValueError. Ensure all filterable keys are listed inmetadata_columns.
Note: In no-JSON-column mode, LlamaIndex internal serialization data (e.g.,
_node_content) is not stored. Node reconstruction falls back to creating a basicTextNodefrom the text and mapped metadata columns. This is sufficient for search and retrieval but does not preserve node relationships or other internal metadata.
Note: In no-JSON-column mode,
delete(ref_doc_id)andadelete(ref_doc_id)raiseValueErrorbecauseref_doc_idis stored in the JSON metadata column. Usedelete_nodes(filters=...)ordelete_by_metadata(filters=...)instead, or addref_doc_idtometadata_columnsto enable filtering on a dedicated column.
Column Class Reference
The Column dataclass defines metadata column schema for new table creation:
| Field | Type | Default | Description |
|---|---|---|---|
name |
str | (required) | Column name (must match a metadata key) |
data_type |
str | (required) | SQL type, e.g. "VARCHAR(255)", "INT", "DECIMAL(10,2)" |
nullable |
bool | True |
Whether the column allows NULL values |
default |
str | None |
SQL default expression for DDL, e.g. "0", "'active'" |
Note:
data_typeanddefaultare validated to prevent SQL injection (no semicolons, comments, or newlines). Only SQL type expressions are allowed.
Note:
defaultonly affects the DDL schema definition (DEFAULTclause inCREATE TABLE). It does not auto-fill missing values duringINSERTthrough this package. When a metadata key is absent,nullable=Falsecolumns raiseValueError, andnullable=Truecolumns insertNULL. To auto-fill defaults, provide the value in the metadata dict before callingadd().
SQL Database
PolarDBXSQLDatabase wraps LlamaIndex's SQLDatabase with PolarDB-X-specific DDL reflection fixes, enabling seamless use with LlamaIndex SQL query engines (e.g. NLSQLTableQueryEngine). It automatically:
- Normalizes tab indentation in
SHOW CREATE TABLEoutput (PolarDB-X uses tabs, standard MySQL uses two spaces) - Fixes ENUM/SET value list spacing (
enum('A', 'B')toenum('A','B')) - Registers a custom
VECTORtype so tables with vector columns do not crash reflection - Auto-swaps
mysql+pymysql://URIs to use the PolarDB-X dialect
from llama_index.vector_stores.polardbx import PolarDBXSQLDatabase
db = PolarDBXSQLDatabase.from_uri(
"mysql+pymysql://user:password@host:3306/your-database"
)
# List tables
tables = db.get_usable_table_names()
# Get table schema info for SQL query engines
info = db.get_single_table_info("your_table")
# Run SQL queries
result = db.run_sql("SELECT COUNT(*) FROM your_table")
Usage with NLSQLTableQueryEngine
from llama_index.core import Settings
from llama_index.core.indices.struct_store import NLSQLTableQueryEngine
from llama_index.vector_stores.polardbx import PolarDBXSQLDatabase
db = PolarDBXSQLDatabase.from_uri(
"mysql+pymysql://user:password@host:3306/your-database"
)
query_engine = NLSQLTableQueryEngine(
sql_database=db,
tables=["orders", "customers"],
)
response = query_engine.query("How many orders were placed last month?")
print(response)
Note:
VECTOR INDEXdefinitions inSHOW CREATE TABLEare not parsed by SQLAlchemy and will be silently skipped with a warning. This is expected — the index info is not needed for SQL query generation. Tables withVECTORcolumns are fully supported.
Usage Examples
Direct Vector Store Operations
from llama_index.vector_stores.polardbx import PolarDBXVectorStore
from llama_index.core.schema import TextNode
vector_store = PolarDBXVectorStore(
host="your-host",
port=3306,
user="your-user",
password="your-password",
database="your-database",
table_name="my_vectors",
embed_dim=1536,
)
# Add nodes
nodes = [
TextNode(text="Hello world", embedding=[0.1, 0.2, ...]),
TextNode(text="PolarDB-X is great", embedding=[0.3, 0.4, ...]),
]
ids = vector_store.add(nodes)
# Query
from llama_index.core.vector_stores import VectorStoreQuery
query = VectorStoreQuery(
query_embedding=[0.1, 0.2, ...],
similarity_top_k=5,
)
result = vector_store.query(query)
for node, score in zip(result.nodes, result.similarities):
print(f"[Score: {score:.4f}] {node.text}")
Search with Metadata Filter
from llama_index.core.vector_stores import (
MetadataFilter,
MetadataFilters,
FilterOperator,
)
# Add nodes with metadata
nodes = [
TextNode(text="Apple is a fruit", embedding=[...], metadata={"category": "fruit", "price": 5}),
TextNode(text="Banana is yellow", embedding=[...], metadata={"category": "fruit", "price": 3}),
TextNode(text="Car is a vehicle", embedding=[...], metadata={"category": "vehicle", "price": 20000}),
]
vector_store.add(nodes)
# Filter: category = "fruit" AND price > 2
filters = MetadataFilters(
filters=[
MetadataFilter(key="category", value="fruit", operator=FilterOperator.EQ),
MetadataFilter(key="price", value=2, operator=FilterOperator.GT),
]
)
query = VectorStoreQuery(query_embedding=[...], similarity_top_k=5, filters=filters)
result = vector_store.query(query)
Supported filter operators:
| Operator | SQL | Description |
|---|---|---|
$eq |
= |
Equal (default for simple values) |
$ne |
!= |
Not equal |
$gt |
> |
Greater than |
$gte |
>= |
Greater than or equal |
$lt |
< |
Less than |
$lte |
<= |
Less than or equal |
$in |
IN |
In a list of values |
$nin |
NOT IN |
Not in a list of values |
MMR Search (Maximal Marginal Relevance)
from llama_index.core.vector_stores import VectorStoreQuery
from llama_index.core.vector_stores.types import VectorStoreQueryMode
# MMR search for diverse results
query = VectorStoreQuery(
query_embedding=[...],
similarity_top_k=4,
mode=VectorStoreQueryMode.MMR,
)
result = vector_store.query(
query,
fetch_k=20, # Candidates to fetch before re-ranking
lambda_mult=0.5, # 0 = max diversity, 1 = max relevance
)
Search Mode Control
from llama_index.core.vector_stores import VectorStoreQuery
query = VectorStoreQuery(
query_embedding=[0.1, 0.2, ...],
similarity_top_k=10,
)
# Force ANN (use vector index for HNSW acceleration)
result = vector_store.query(query, search_type="ann")
# Force KNN (full table scan, bypass vector index)
result = vector_store.query(query, search_type="knn")
# Let the optimizer decide (default)
result = vector_store.query(query, search_type="auto")
# Tune ef_search per query (higher = more accurate, slower)
result = vector_store.query(query, ef_search=100)
Dynamic Vector Index Management
# Create a vector index at runtime
vector_store.apply_vector_index(
index_name="my_vi",
m=16,
distance="cosine",
ef_construction=200, # newer versions only, ignored on older versions
)
# Drop the vector index
vector_store.drop_vector_index()
# Rebuild the index to reclaim space and improve recall
vector_store.optimize()
Index Monitoring (Newer Versions Only)
# Get runtime statistics
stats = vector_store.get_stats()
print(stats) # e.g. {"Vidx_query_count": 100, "Vidx_load_node_hits": 950, ...}
# Preload HNSW index into memory cache to eliminate cold-start latency
vector_store.preload_index()
# Check if preloading would fit in cache
check_result = vector_store.preload_check()
print(check_result)
# Diagnose index health
health = vector_store.explain_index_health()
print(health)
Delete and Manage Nodes
from llama_index.core.vector_stores import (
MetadataFilters,
MetadataFilter,
FilterOperator,
)
# Delete by ref_doc_id
vector_store.delete(ref_doc_id="doc-001")
# Delete by node_ids
vector_store.delete_nodes(node_ids=["node-1", "node-2"])
# Delete by metadata filters (alternative to node_ids)
filters = MetadataFilters(filters=[
MetadataFilter(key="status", value="deleted", operator=FilterOperator.EQ),
])
vector_store.delete_nodes(filters=filters)
# Get nodes by node_ids
nodes = vector_store.get_nodes(node_ids=["node-1", "node-2"])
# Get nodes by metadata filters (alternative to node_ids)
nodes = vector_store.get_nodes(filters=filters)
# Count vectors
count = vector_store.count()
# Clear all data (TRUNCATE TABLE)
vector_store.clear()
# Drop the entire table
vector_store.drop()
# Search nodes by metadata only (no vector similarity)
nodes = vector_store.search_by_metadata(filters=filters, limit=10)
# Delete nodes matching metadata conditions
deleted_count = vector_store.delete_by_metadata(filters=filters)
print(f"Deleted {deleted_count} nodes")
# Close connections
vector_store.close()
Async API
All public methods have async equivalents:
import asyncio
async def main():
# Add nodes
ids = await vector_store.async_add(nodes)
# Query
result = await vector_store.aquery(query)
# Delete
await vector_store.adelete(ref_doc_id="doc-001")
# Delete nodes
await vector_store.adelete_nodes(node_ids=["node-1"])
# Get nodes
nodes = await vector_store.aget_nodes(node_ids=["node-1", "node-2"])
# Count
count = await vector_store.acount()
# Clear
await vector_store.aclear()
# Drop the entire table
await vector_store.adrop()
# Metadata-based operations
from llama_index.core.vector_stores import MetadataFilters, MetadataFilter, FilterOperator
filters = MetadataFilters(filters=[
MetadataFilter(key="category", value="fruit", operator=FilterOperator.EQ),
])
nodes = await vector_store.asearch_by_metadata(filters=filters, limit=10)
deleted = await vector_store.adelete_by_metadata(filters=filters)
# Dynamic index management
await vector_store.aapply_vector_index(index_name="vi", m=16)
await vector_store.adrop_vector_index()
await vector_store.aoptimize()
# newer version monitoring
stats = await vector_store.aget_stats()
await vector_store.apreload_index()
check = await vector_store.apreload_check()
health = await vector_store.aexplain_index_health()
# Close connections
await vector_store.aclose()
asyncio.run(main())
Partitioned Tables
PolarDB-X is a distributed database that supports table partitioning for scalability. This package supports creating partitioned vector tables and standalone partitioned tables.
Vector Store with Partitioning
from llama_index.vector_stores.polardbx import PolarDBXVectorStore
# HASH partitioning (8 partitions on the id column)
vector_store = PolarDBXVectorStore(
host="your-host", port=3306, user="your-user", password="your-password",
database="your-database", table_name="partitioned_vectors",
embed_dim=1536,
partition_by="HASH", # "HASH", "KEY", "RANGE", or "LIST"
partition_column="id", # column to partition on (default: "id")
partitions=8, # number of partitions (HASH/KEY only)
)
# Broadcast table (full copy on every DN node)
vector_store = PolarDBXVectorStore(
..., broadcast=True,
)
# RANGE partitioning
vector_store = PolarDBXVectorStore(
..., partition_by="RANGE", partition_column="id",
partition_defs=[
{"name": "p0", "values_less_than": 1000},
{"name": "p1", "values_less_than": "MAXVALUE"},
],
)
# With LOCALITY (pin table to a specific DN node)
vector_store = PolarDBXVectorStore(
..., locality="dn=your-dn-node-name",
)
Note: Partitioned vector tables are not supported on certain PolarDB-X instances. The package automatically detects this and raises
NotSupportedErrorif you attempt to use partitioning on an incompatible version.Note: When partitioning is enabled, the
node_idUNIQUE INDEX is automatically downgraded to a regular INDEX. PolarDB-X requires that unique indexes include the partition key, and since thenode_idcolumn (or customnode_id_column) is not the partition key, a UNIQUE constraint would be incompatible with partitioning. Theadd()method automatically adapts: non-partitioned tables useON DUPLICATE KEY UPDATE, while partitioned tables use DELETE-then-INSERT to preserve upsert semantics.Note: For vector tables,
partition_columnmust match theid_columnvalue (default:"id"). This is enforced at init time. Usecreate_partitioned_table()if you need to partition on a different column.Note: LIST partitioning is generally not practical for VectorStore tables because the
idcolumn is a UUID string — LIST requires exact value enumeration, which is infeasible for UUIDs. Use HASH or KEY partitioning for VectorStore tables instead. LIST partitioning is better suited forcreate_partitioned_table()on tables with known, bounded value sets (e.g., region codes).
Standalone Partitioned Table (Non-Vector)
For non-vector tables (e.g., for SQL agents), use create_partitioned_table:
from llama_index.vector_stores.polardbx import create_partitioned_table
# HASH partitioning
create_partitioned_table(
uri="mysql+pymysql://user:password@host:3306/database",
table_name="orders",
columns=[
"id BIGINT NOT NULL AUTO_INCREMENT",
"user_id BIGINT NOT NULL",
"amount DECIMAL(10,2)",
"created_at DATETIME",
"PRIMARY KEY (id)",
],
partition_by="HASH",
partition_column="user_id",
partitions=16,
)
# Broadcast table (dimension table, full copy on every DN)
create_partitioned_table(
uri="mysql+pymysql://user:password@host:3306/database",
table_name="dim_currency",
columns=["code VARCHAR(10)", "name VARCHAR(100)", "PRIMARY KEY (code)"],
broadcast=True,
)
# RANGE partitioning
create_partitioned_table(
uri="mysql+pymysql://user:password@host:3306/database",
table_name="logs",
columns=["id BIGINT NOT NULL", "ts DATETIME", "PRIMARY KEY (id)"],
partition_by="RANGE",
partition_column="id",
partition_defs=[
{"name": "p0", "values_less_than": 1000000},
{"name": "p1", "values_less_than": 2000000},
{"name": "p2", "values_less_than": "MAXVALUE"},
],
)
# LIST partitioning
create_partitioned_table(
uri="mysql+pymysql://user:password@host:3306/database",
table_name="customers",
columns=[
"id BIGINT NOT NULL AUTO_INCREMENT",
"region VARCHAR(20) NOT NULL",
"name VARCHAR(255)",
"PRIMARY KEY (id, region)",
],
partition_by="LIST",
partition_column="region",
partition_defs=[
{"name": "p_east", "values_in": ["east"]},
{"name": "p_west", "values_in": ["west"]},
{"name": "p_other", "values_in": ["north", "south"]},
],
)
Supported partition strategies:
| Strategy | Parameters | Description |
|---|---|---|
HASH |
partition_column, partitions |
Hash partitioning by column value |
KEY |
partition_column, partitions |
Key partitioning (single column) |
RANGE |
partition_column, partition_defs |
Range partitioning with explicit boundaries |
LIST |
partition_column, partition_defs |
List partitioning with explicit value lists |
BROADCAST |
(none) | Full table copy on every DN node |
LOCALITY |
locality |
Pin table to a specific storage node |
Configuration Options
| Parameter | Type | Default | Description |
|---|---|---|---|
host |
str | - | PolarDB-X host address |
port |
int | - | PolarDB-X port number |
user |
str | - | Username |
password |
str | - | Password |
database |
str | - | Database name |
table_name |
str | "llama_index_table" |
Table name for vector storage |
embed_dim |
int | 1536 | Embedding dimension |
distance_strategy |
str | "cosine" |
Distance function: "cosine", "euclidean", or "inner_product" (newer versions) |
default_m |
int | 6 | HNSW index M parameter (DB allows 3-200; client validates positive int only) |
perform_setup |
bool | True | Whether to auto-create table on init |
debug |
bool | False | Enable SQLAlchemy echo mode |
ef_construction |
int | None | HNSW build-time candidate list size (DB allows 5-1000, newer versions only; client validates positive int only) |
ssl |
bool | False | Enable TLS/SSL encryption |
ssl_ca |
str | None | Path to CA certificate for SSL verification (only effective when ssl=True) |
vector_index_name |
str | None | Vector index name for FORCE INDEX hints (auto-detected if None) |
connection_retries |
int | 3 | Number of connection retry attempts during initialization |
retry_delay |
float | 1.0 | Delay between retry attempts in seconds |
partition_by |
str | None | Partition strategy: "HASH", "KEY", "RANGE", or "LIST" |
partitions |
int | 0 | Number of partitions (required for HASH/KEY) |
partition_column |
str | None | Column to partition on (must match id_column value for vector tables; defaults to id_column value at runtime) |
broadcast |
bool | False | Create a broadcast table (full copy on every DN) |
locality |
str | None | Pin table to a specific DN node, e.g. "dn=node-name" |
partition_defs |
list | None | Partition definitions for RANGE/LIST (see examples above) |
id_column |
str | "id" |
Custom name for the primary key column (UUID VARCHAR(36)) |
node_id_column |
str | "node_id" |
Custom name for the LlamaIndex node_id column (VARCHAR(255)) |
text_column |
str | "text" |
Custom name for the text content column (LONGTEXT) |
embedding_column |
str | "embedding" |
Custom name for the vector embedding column (VECTOR(N)) |
metadata_json_column |
str | "metadata" |
Custom name for the JSON metadata column. Set None to disable the JSON column (requires metadata_columns to be non-empty) |
metadata_columns |
list | None | List of Column objects or column name strings to promote metadata keys to dedicated typed columns (see Custom Column Schema) |
**kwargs |
- | - | Additional pymysql connection arguments (e.g. ssl_cert, ssl_key, ssl_verify_ca, ssl_verify_identity, ssl_disabled, connect_timeout, read_timeout, write_timeout, charset, collation, autocommit, unix_socket) |
PolarDB-X Vector Functions Used
This integration uses PolarDB-X's native vector functions:
VECTOR(N)— Vector column data type with N dimensionsVEC_FROMTEXT('[1,2,3]')— Convert JSON array string to vectorVEC_TOTEXT(vector)— Convert vector to JSON array stringVEC_DISTANCE(v1, v2)— Auto-inferred distance function (newer versions)VEC_DISTANCE_COSINE(v1, v2)— Cosine distance (old versions)VEC_DISTANCE_EUCLIDEAN(v1, v2)— Euclidean distance (old versions)VEC_DISTANCE_INNER_PRODUCT(v1, v2)— Inner product distance (used when auto-inference is unavailable on older versions; INNER_PRODUCT distance itself requires newer versions)VECTOR_DIM(v)— Get vector dimension (newer versions)VECTOR INDEX (col) M=N DISTANCE=COSINE— HNSW vector index DDLEF_CONSTRUCTION=N— HNSW build-time parameter in DDL (newer versions)SET SESSION vidx_hnsw_ef_search = N— Per-session search width tuningSHOW GLOBAL STATUS LIKE 'Vidx%'— Runtime index statisticsCALL dbms_vidx.preload(db, table, col)— Preload index into cache (newer versions)CALL dbms_vidx.preload_check(db, table, col)— Check preload feasibility (newer versions)information_schema.VECTOR_INDEXES— Vector index metadata view (newer versions)
Error Handling
When using features that require newer PolarDB-X versions, a NotSupportedError is raised on older versions. Features that require newer versions include:
distance_strategy="inner_product"(init-time validation)preload_index()/apreload_index()preload_check()/apreload_check()explain_index_health()/aexplain_index_health()- Partitioned vector table creation (
partition_by,broadcaston incompatible instances) - Partitioned standalone table creation via
create_partitioned_table()on incompatible instances
from llama_index.vector_stores.polardbx import PolarDBXVectorStore, NotSupportedError
try:
vector_store.preload_index()
except NotSupportedError as e:
print(f"Feature not supported: {e}")
Development
This package uses uv for dependency management.
# Install dependencies
uv sync --group dev
# Run unit tests
pytest tests/unit_tests/ -v
# Run integration tests (requires a running PolarDB-X instance)
pytest tests/integration_tests/ -v
# Lint
ruff check llama_index/
License
MIT
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file llama_index_vector_stores_polardbx-0.3.1.tar.gz.
File metadata
- Download URL: llama_index_vector_stores_polardbx-0.3.1.tar.gz
- Upload date:
- Size: 51.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
764765a901466bc8190a2ac1d3a04eb80df5b6a6648960450cd6cd61a8bcde7d
|
|
| MD5 |
a03457f580f140a347ce424079785a69
|
|
| BLAKE2b-256 |
406017a4094f3185e9b1f3c38f9eb3c970379258cd1883e5a7aee9f30623befa
|
File details
Details for the file llama_index_vector_stores_polardbx-0.3.1-py3-none-any.whl.
File metadata
- Download URL: llama_index_vector_stores_polardbx-0.3.1-py3-none-any.whl
- Upload date:
- Size: 47.0 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
21a6cd39d739860c2832bb7679da4717ee89c8a5639dadd8955524f07d43b6ef
|
|
| MD5 |
617bcc0c682884ee8996af5b032fd663
|
|
| BLAKE2b-256 |
95c38b53b90218ac304040e37148a8ee714561d051c8a29d55658d11c8aa1b1e
|