Add GIN index support for text array metadata in PostgreSQL vector store

Fixes #20128

Enable automatic GIN index creation for text array metadata fields in the PostgreSQL vector store. This allows fast array membership queries using PostgreSQL operators (?|, ?&, @>) without requiring raw SQL workarounds.

Changes:
- Extended PGType to support text[] array type
- Modified get_data_model() to create GIN indices for array fields and BTREE indices for scalar fields
- Cast metadata to JSONB in GIN index creation for compatibility with both JSON and JSONB columns
- Added comprehensive tests covering GIN index creation, CONTAINS, ANY, ALL operators, and mixed BTREE/GIN queries
- Tests use PostgreSQL system catalogs (pg_class, pg_am) for type-safe index verification

This maintains backward compatibility - existing BTREE indices continue working, and GIN indices are only created when text[] is specified in indexed_metadata_keys.

Author: Jash Shah

llama-index-integrations/vector_stores/llama-index-vector-stores-postgres/llama_index/vector_stores/postgres/base.py

@@ -49,6 +49,8 @@
     "date",
     "timestamp",
     "uuid",
+    # Array type for GIN indexing
+    "text[]",
 ]
 
 
@@ -81,6 +83,7 @@ def get_data_model(
     from pgvector.sqlalchemy import Vector
     from sqlalchemy import Column, Computed
     from sqlalchemy.dialects.postgresql import (
+        ARRAY,
         BIGINT,
         JSON,
         JSONB,
@@ -105,6 +108,8 @@ def get_data_model(
         "date": Date,
         "timestamp": DateTime,
         "uuid": UUID,
+        # Array type for GIN indexing
+        "text[]": ARRAY(String),
     }
 
     indexed_metadata_keys = indexed_metadata_keys or set()
@@ -131,15 +136,33 @@ class TSVector(TypeDecorator):
     else:
         embedding_col = Column(Vector(embed_dim))  # type: ignore
 
-    metadata_indices = [
+    # BTREE indices for scalar types (existing behavior)
+    btree_indices = [
         Index(
             f"{indexname}_{key}_{pg_type.replace(' ', '_')}",
             cast(column("metadata_").op("->>")(key), pg_type_map[pg_type]),
             postgresql_using="btree",
         )
         for key, pg_type in indexed_metadata_keys
+        if pg_type != "text[]"
     ]
 
+    # GIN indices for text arrays (enables fast array operations with ?|, ?&, @> operators)
+    gin_indices = [
+        Index(
+            f"{indexname}_{key}_gin",
+            cast(
+                column("metadata_").op("->")(key), JSONB
+            ),  # Cast to JSONB for GIN index compatibility
+            postgresql_using="gin",
+        )
+        for key, pg_type in indexed_metadata_keys
+        if pg_type == "text[]"
+    ]
+
+    # Combine both types of indices
+    metadata_indices = btree_indices + gin_indices
+
     if hybrid_search:
 
         class HybridAbstractData(base):  # type: ignore
@@ -677,9 +700,9 @@ def _build_filter_clause(self, filter_: MetadataFilter) -> Any:
                 f"({filter_value})"
             )
         elif filter_.operator in [FilterOperator.ANY, FilterOperator.ALL]:
-            # Expects a list stored in the metadata, and a single value to compare
-
-            # We apply same logic as above, but as an array
+            # Expects a text array stored in the metadata, and a list of values to compare
+            # Works with text[] arrays using PostgreSQL ?| (ANY) and ?& (ALL) operators
+            # Example: metadata_::jsonb->'tags' ?| array['AI', 'ML']
             filter_value = ", ".join(f"'{e}'" for e in filter_.value)
 
             return text(

llama-index-integrations/vector_stores/llama-index-vector-stores-postgres/pyproject.toml

@@ -27,7 +27,7 @@ dev = [
 
 [project]
 name = "llama-index-vector-stores-postgres"
-version = "0.7.0"
+version = "0.7.1"
 description = "llama-index vector_stores postgres integration"
 authors = [{name = "Your Name", email = "[email protected]"}]
 requires-python = ">=3.9,<4.0"