damccorm commented on code in PR #36654: URL: https://github.com/apache/beam/pull/36654#discussion_r2475442529
########## sdks/python/apache_beam/ml/rag/ingestion/spanner.py: ########## @@ -0,0 +1,660 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Cloud Spanner vector store writer for RAG pipelines. + +This module provides a writer for storing embeddings and associated metadata +in Google Cloud Spanner. It supports flexible schema configuration with the +ability to flatten metadata fields into dedicated columns. + +Example usage: + + Default schema (id, embedding, content, metadata): + >>> config = SpannerVectorWriterConfig( + ... project_id="my-project", + ... instance_id="my-instance", + ... database_id="my-db", + ... table_name="embeddings" + ... ) + + Flattened metadata fields: + >>> specs = ( + ... SpannerColumnSpecsBuilder() + ... .with_id_spec() + ... .with_embedding_spec() + ... .with_content_spec() + ... .add_metadata_field("source", str) + ... .add_metadata_field("page_number", int, default=0) + ... .with_metadata_spec() + ... .build() + ... ) + >>> config = SpannerVectorWriterConfig( + ... project_id="my-project", + ... instance_id="my-instance", + ... database_id="my-db", + ... table_name="embeddings", + ... column_specs=specs + ... ) + +Spanner schema example: + + CREATE TABLE embeddings ( + id STRING(1024) NOT NULL, + embedding ARRAY<FLOAT32>(vector_length=>768), + content STRING(MAX), + source STRING(MAX), + page_number INT64, + metadata JSON + ) PRIMARY KEY (id) +""" + +import functools +import json +from dataclasses import dataclass +from typing import Any +from typing import Callable +from typing import List +from typing import Literal +from typing import NamedTuple +from typing import Optional +from typing import Type + +import apache_beam as beam +from apache_beam.coders import registry +from apache_beam.coders.row_coder import RowCoder +from apache_beam.io.gcp import spanner +from apache_beam.ml.rag.ingestion.base import VectorDatabaseWriteConfig +from apache_beam.ml.rag.types import Chunk + + +@dataclass +class SpannerColumnSpec: + """Column specification for Spanner vector writes. + + Defines how to extract and format values from Chunks for insertion into + Spanner table columns. Each spec maps to one column in the target table. + + Attributes: + column_name: Name of the Spanner table column + python_type: Python type for the NamedTuple field (required for RowCoder) + value_fn: Function to extract value from a Chunk + + Examples: + String column: + >>> SpannerColumnSpec( + ... column_name="id", + ... python_type=str, + ... value_fn=lambda chunk: chunk.id + ... ) + + Array column with conversion: + >>> SpannerColumnSpec( + ... column_name="embedding", + ... python_type=List[float], + ... value_fn=lambda chunk: chunk.embedding.dense_embedding + ... ) + """ + column_name: str + python_type: Type + value_fn: Callable[[Chunk], Any] + + +def _extract_and_convert(extract_fn, convert_fn, chunk): + if convert_fn: + return convert_fn(extract_fn(chunk)) + return extract_fn(chunk) + + +class SpannerColumnSpecsBuilder: + """Builder for creating Spanner column specifications. + + Provides a fluent API for defining table schemas and how to populate them + from Chunk objects. Supports standard Chunk fields (id, embedding, content, + metadata) and flattening metadata fields into dedicated columns. + + Example: + >>> specs = ( + ... SpannerColumnSpecsBuilder() + ... .with_id_spec() + ... .with_embedding_spec() + ... .with_content_spec() + ... .add_metadata_field("source", str) + ... .with_metadata_spec() + ... .build() + ... ) + """ + def __init__(self): + self._specs: List[SpannerColumnSpec] = [] + + @staticmethod + def with_defaults() -> 'SpannerColumnSpecsBuilder': + """Create builder with default schema. + + Default schema includes: + - id (STRING): Chunk ID + - embedding (ARRAY<FLOAT32>): Dense embedding vector + - content (STRING): Chunk content text + - metadata (JSON): Full metadata as JSON + + Returns: + Builder with default column specifications + """ + return ( + SpannerColumnSpecsBuilder().with_id_spec().with_embedding_spec(). + with_content_spec().with_metadata_spec()) + + def with_id_spec( + self, + column_name: str = "id", + python_type: Type = str, + extract_fn: Optional[Callable[[Chunk], Any]] = lambda chunk: chunk.id, + convert_fn: Optional[Callable[[Any], Any]] = None + ) -> 'SpannerColumnSpecsBuilder': + """Add ID column specification. + + Args: + column_name: Column name (default: "id") + python_type: Python type (default: str) + extract_fn: Value extractor (default: lambda chunk: chunk.id) + convert_fn: Optional converter (e.g., to cast to int) + + Returns: + Self for method chaining + + Examples: + Default string ID: + >>> builder.with_id_spec() + + Integer ID with conversion: + >>> builder.with_id_spec( + ... python_type=int, + ... convert_fn=lambda id: int(id.split('_')[1]) + ... ) + """ + + self._specs.append( + SpannerColumnSpec( + column_name=column_name, + python_type=python_type, + value_fn=functools.partial( + _extract_and_convert, extract_fn, convert_fn))) + return self + + def with_embedding_spec( + self, + column_name: str = "embedding", + extract_fn: Optional[Callable[[Chunk], List[float]]] = None, + convert_fn: Optional[Callable[[List[float]], List[float]]] = None + ) -> 'SpannerColumnSpecsBuilder': + """Add embedding array column (ARRAY<FLOAT32> or ARRAY<FLOAT64>). + + Args: + column_name: Column name (default: "embedding") + extract_fn: Value extractor (default: chunk.embedding.dense_embedding) + convert_fn: Optional converter (e.g., normalize, quantize) + + Returns: + Self for method chaining + + Examples: + Default embedding: + >>> builder.with_embedding_spec() + + Normalized embedding: + >>> def normalize(vec): + ... norm = (sum(x**2 for x in vec) ** 0.5) or 1.0 + ... return [x/norm for x in vec] + >>> builder.with_embedding_spec(convert_fn=normalize) + + Rounded precision: + >>> builder.with_embedding_spec( + ... convert_fn=lambda vec: [round(x, 4) for x in vec] + ... ) + """ + def default_fn(chunk: Chunk) -> List[float]: + if chunk.embedding is None or chunk.embedding.dense_embedding is None: + raise ValueError(f'Chunk must contain embedding: {chunk}') + return chunk.embedding.dense_embedding + + extract_fn = extract_fn or default_fn + + self._specs.append( + SpannerColumnSpec( + column_name=column_name, + python_type=List[float], + value_fn=functools.partial( + _extract_and_convert, extract_fn, convert_fn))) + return self + + def with_content_spec( + self, + column_name: str = "content", + python_type: Type = str, + extract_fn: Optional[Callable[[Chunk], Any]] = None, + convert_fn: Optional[Callable[[Any], Any]] = None + ) -> 'SpannerColumnSpecsBuilder': + """Add content column. + + Args: + column_name: Column name (default: "content") + python_type: Python type (default: str) + extract_fn: Value extractor (default: chunk.content.text) + convert_fn: Optional converter + + Returns: + Self for method chaining + + Examples: + Default text content: + >>> builder.with_content_spec() + + Content length as integer: + >>> builder.with_content_spec( + ... column_name="content_length", + ... python_type=int, + ... convert_fn=lambda text: len(text.split()) + ... ) + + Truncated content: + >>> builder.with_content_spec( + ... convert_fn=lambda text: text[:1000] + ... ) + """ + def default_fn(chunk: Chunk) -> str: + if chunk.content.text is None: + raise ValueError(f'Chunk must contain content: {chunk}') + return chunk.content.text + + extract_fn = extract_fn or default_fn + + self._specs.append( + SpannerColumnSpec( + column_name=column_name, + python_type=python_type, + value_fn=functools.partial( + _extract_and_convert, extract_fn, convert_fn))) + return self + + def with_metadata_spec( + self, + column_name: str = "metadata", + value_fn: Optional[Callable[[Chunk], Any]] = None + ) -> 'SpannerColumnSpecsBuilder': + """Add metadata JSON column. + + Stores the full metadata dictionary as a JSON string in Spanner. + + Args: + column_name: Column name (default: "metadata") + value_fn: Value extractor (default: lambda chunk: chunk.metadata) + + Returns: + Self for method chaining + + Note: + Metadata is automatically converted to JSON string using json.dumps() Review Comment: ```suggestion Metadata is automatically converted to JSON string using json.dumps() if no value_fn is provided ``` ########## sdks/python/apache_beam/ml/rag/ingestion/spanner.py: ########## @@ -0,0 +1,660 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Cloud Spanner vector store writer for RAG pipelines. + +This module provides a writer for storing embeddings and associated metadata +in Google Cloud Spanner. It supports flexible schema configuration with the +ability to flatten metadata fields into dedicated columns. + +Example usage: + + Default schema (id, embedding, content, metadata): + >>> config = SpannerVectorWriterConfig( + ... project_id="my-project", + ... instance_id="my-instance", + ... database_id="my-db", + ... table_name="embeddings" + ... ) + + Flattened metadata fields: + >>> specs = ( + ... SpannerColumnSpecsBuilder() + ... .with_id_spec() + ... .with_embedding_spec() + ... .with_content_spec() + ... .add_metadata_field("source", str) + ... .add_metadata_field("page_number", int, default=0) + ... .with_metadata_spec() + ... .build() + ... ) + >>> config = SpannerVectorWriterConfig( + ... project_id="my-project", + ... instance_id="my-instance", + ... database_id="my-db", + ... table_name="embeddings", + ... column_specs=specs + ... ) + +Spanner schema example: + + CREATE TABLE embeddings ( + id STRING(1024) NOT NULL, + embedding ARRAY<FLOAT32>(vector_length=>768), + content STRING(MAX), + source STRING(MAX), + page_number INT64, + metadata JSON + ) PRIMARY KEY (id) +""" + +import functools +import json +from dataclasses import dataclass +from typing import Any +from typing import Callable +from typing import List +from typing import Literal +from typing import NamedTuple +from typing import Optional +from typing import Type + +import apache_beam as beam +from apache_beam.coders import registry +from apache_beam.coders.row_coder import RowCoder +from apache_beam.io.gcp import spanner +from apache_beam.ml.rag.ingestion.base import VectorDatabaseWriteConfig +from apache_beam.ml.rag.types import Chunk + + +@dataclass +class SpannerColumnSpec: + """Column specification for Spanner vector writes. + + Defines how to extract and format values from Chunks for insertion into + Spanner table columns. Each spec maps to one column in the target table. + + Attributes: + column_name: Name of the Spanner table column + python_type: Python type for the NamedTuple field (required for RowCoder) + value_fn: Function to extract value from a Chunk + + Examples: + String column: + >>> SpannerColumnSpec( + ... column_name="id", + ... python_type=str, + ... value_fn=lambda chunk: chunk.id + ... ) + + Array column with conversion: + >>> SpannerColumnSpec( + ... column_name="embedding", + ... python_type=List[float], + ... value_fn=lambda chunk: chunk.embedding.dense_embedding + ... ) + """ + column_name: str + python_type: Type + value_fn: Callable[[Chunk], Any] + + +def _extract_and_convert(extract_fn, convert_fn, chunk): + if convert_fn: + return convert_fn(extract_fn(chunk)) + return extract_fn(chunk) + + +class SpannerColumnSpecsBuilder: + """Builder for creating Spanner column specifications. + + Provides a fluent API for defining table schemas and how to populate them + from Chunk objects. Supports standard Chunk fields (id, embedding, content, + metadata) and flattening metadata fields into dedicated columns. + + Example: + >>> specs = ( + ... SpannerColumnSpecsBuilder() + ... .with_id_spec() + ... .with_embedding_spec() + ... .with_content_spec() + ... .add_metadata_field("source", str) + ... .with_metadata_spec() + ... .build() + ... ) + """ + def __init__(self): + self._specs: List[SpannerColumnSpec] = [] + + @staticmethod + def with_defaults() -> 'SpannerColumnSpecsBuilder': + """Create builder with default schema. + + Default schema includes: + - id (STRING): Chunk ID + - embedding (ARRAY<FLOAT32>): Dense embedding vector + - content (STRING): Chunk content text + - metadata (JSON): Full metadata as JSON + + Returns: + Builder with default column specifications + """ + return ( + SpannerColumnSpecsBuilder().with_id_spec().with_embedding_spec(). + with_content_spec().with_metadata_spec()) + + def with_id_spec( + self, + column_name: str = "id", + python_type: Type = str, + extract_fn: Optional[Callable[[Chunk], Any]] = lambda chunk: chunk.id, + convert_fn: Optional[Callable[[Any], Any]] = None Review Comment: If we need it to match other ios, it is probably fine, just realized we might not need it ########## sdks/python/apache_beam/ml/rag/ingestion/spanner.py: ########## @@ -0,0 +1,660 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Cloud Spanner vector store writer for RAG pipelines. + +This module provides a writer for storing embeddings and associated metadata +in Google Cloud Spanner. It supports flexible schema configuration with the +ability to flatten metadata fields into dedicated columns. + +Example usage: + + Default schema (id, embedding, content, metadata): + >>> config = SpannerVectorWriterConfig( + ... project_id="my-project", + ... instance_id="my-instance", + ... database_id="my-db", + ... table_name="embeddings" + ... ) + + Flattened metadata fields: + >>> specs = ( + ... SpannerColumnSpecsBuilder() + ... .with_id_spec() + ... .with_embedding_spec() + ... .with_content_spec() + ... .add_metadata_field("source", str) + ... .add_metadata_field("page_number", int, default=0) + ... .with_metadata_spec() + ... .build() + ... ) + >>> config = SpannerVectorWriterConfig( + ... project_id="my-project", + ... instance_id="my-instance", + ... database_id="my-db", + ... table_name="embeddings", + ... column_specs=specs + ... ) + +Spanner schema example: + + CREATE TABLE embeddings ( + id STRING(1024) NOT NULL, + embedding ARRAY<FLOAT32>(vector_length=>768), + content STRING(MAX), + source STRING(MAX), + page_number INT64, + metadata JSON + ) PRIMARY KEY (id) +""" + +import functools +import json +from dataclasses import dataclass +from typing import Any +from typing import Callable +from typing import List +from typing import Literal +from typing import NamedTuple +from typing import Optional +from typing import Type + +import apache_beam as beam +from apache_beam.coders import registry +from apache_beam.coders.row_coder import RowCoder +from apache_beam.io.gcp import spanner +from apache_beam.ml.rag.ingestion.base import VectorDatabaseWriteConfig +from apache_beam.ml.rag.types import Chunk + + +@dataclass +class SpannerColumnSpec: + """Column specification for Spanner vector writes. + + Defines how to extract and format values from Chunks for insertion into + Spanner table columns. Each spec maps to one column in the target table. + + Attributes: + column_name: Name of the Spanner table column + python_type: Python type for the NamedTuple field (required for RowCoder) + value_fn: Function to extract value from a Chunk + + Examples: + String column: + >>> SpannerColumnSpec( + ... column_name="id", + ... python_type=str, + ... value_fn=lambda chunk: chunk.id + ... ) + + Array column with conversion: + >>> SpannerColumnSpec( + ... column_name="embedding", + ... python_type=List[float], + ... value_fn=lambda chunk: chunk.embedding.dense_embedding + ... ) + """ + column_name: str + python_type: Type + value_fn: Callable[[Chunk], Any] + + +def _extract_and_convert(extract_fn, convert_fn, chunk): + if convert_fn: + return convert_fn(extract_fn(chunk)) + return extract_fn(chunk) + + +class SpannerColumnSpecsBuilder: + """Builder for creating Spanner column specifications. + + Provides a fluent API for defining table schemas and how to populate them + from Chunk objects. Supports standard Chunk fields (id, embedding, content, + metadata) and flattening metadata fields into dedicated columns. + + Example: + >>> specs = ( + ... SpannerColumnSpecsBuilder() + ... .with_id_spec() + ... .with_embedding_spec() + ... .with_content_spec() + ... .add_metadata_field("source", str) + ... .with_metadata_spec() + ... .build() + ... ) + """ + def __init__(self): + self._specs: List[SpannerColumnSpec] = [] + + @staticmethod + def with_defaults() -> 'SpannerColumnSpecsBuilder': + """Create builder with default schema. + + Default schema includes: + - id (STRING): Chunk ID + - embedding (ARRAY<FLOAT32>): Dense embedding vector + - content (STRING): Chunk content text + - metadata (JSON): Full metadata as JSON + + Returns: + Builder with default column specifications + """ + return ( + SpannerColumnSpecsBuilder().with_id_spec().with_embedding_spec(). + with_content_spec().with_metadata_spec()) + + def with_id_spec( + self, + column_name: str = "id", + python_type: Type = str, + extract_fn: Optional[Callable[[Chunk], Any]] = lambda chunk: chunk.id, + convert_fn: Optional[Callable[[Any], Any]] = None Review Comment: Is there a reason to separate extract_fn and convert_fn (here or elsewhere)? ########## sdks/python/apache_beam/ml/rag/ingestion/spanner.py: ########## @@ -0,0 +1,660 @@ +# Licensed to the Apache Software Foundation (ASF) under one or more +# contributor license agreements. See the NOTICE file distributed with +# this work for additional information regarding copyright ownership. +# The ASF licenses this file to You under the Apache License, Version 2.0 +# (the "License"); you may not use this file except in compliance with +# the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +"""Cloud Spanner vector store writer for RAG pipelines. + +This module provides a writer for storing embeddings and associated metadata +in Google Cloud Spanner. It supports flexible schema configuration with the +ability to flatten metadata fields into dedicated columns. + +Example usage: + + Default schema (id, embedding, content, metadata): + >>> config = SpannerVectorWriterConfig( + ... project_id="my-project", + ... instance_id="my-instance", + ... database_id="my-db", + ... table_name="embeddings" + ... ) + + Flattened metadata fields: + >>> specs = ( + ... SpannerColumnSpecsBuilder() + ... .with_id_spec() + ... .with_embedding_spec() + ... .with_content_spec() + ... .add_metadata_field("source", str) + ... .add_metadata_field("page_number", int, default=0) + ... .with_metadata_spec() + ... .build() + ... ) + >>> config = SpannerVectorWriterConfig( + ... project_id="my-project", + ... instance_id="my-instance", + ... database_id="my-db", + ... table_name="embeddings", + ... column_specs=specs + ... ) + +Spanner schema example: + + CREATE TABLE embeddings ( + id STRING(1024) NOT NULL, + embedding ARRAY<FLOAT32>(vector_length=>768), + content STRING(MAX), + source STRING(MAX), + page_number INT64, + metadata JSON + ) PRIMARY KEY (id) +""" + +import functools +import json +from dataclasses import dataclass +from typing import Any +from typing import Callable +from typing import List +from typing import Literal +from typing import NamedTuple +from typing import Optional +from typing import Type + +import apache_beam as beam +from apache_beam.coders import registry +from apache_beam.coders.row_coder import RowCoder +from apache_beam.io.gcp import spanner +from apache_beam.ml.rag.ingestion.base import VectorDatabaseWriteConfig +from apache_beam.ml.rag.types import Chunk + + +@dataclass +class SpannerColumnSpec: + """Column specification for Spanner vector writes. + + Defines how to extract and format values from Chunks for insertion into + Spanner table columns. Each spec maps to one column in the target table. + + Attributes: + column_name: Name of the Spanner table column + python_type: Python type for the NamedTuple field (required for RowCoder) + value_fn: Function to extract value from a Chunk + + Examples: + String column: + >>> SpannerColumnSpec( + ... column_name="id", + ... python_type=str, + ... value_fn=lambda chunk: chunk.id + ... ) + + Array column with conversion: + >>> SpannerColumnSpec( + ... column_name="embedding", + ... python_type=List[float], + ... value_fn=lambda chunk: chunk.embedding.dense_embedding + ... ) + """ + column_name: str + python_type: Type + value_fn: Callable[[Chunk], Any] + + +def _extract_and_convert(extract_fn, convert_fn, chunk): + if convert_fn: + return convert_fn(extract_fn(chunk)) + return extract_fn(chunk) + + +class SpannerColumnSpecsBuilder: + """Builder for creating Spanner column specifications. + + Provides a fluent API for defining table schemas and how to populate them + from Chunk objects. Supports standard Chunk fields (id, embedding, content, + metadata) and flattening metadata fields into dedicated columns. + + Example: + >>> specs = ( + ... SpannerColumnSpecsBuilder() + ... .with_id_spec() + ... .with_embedding_spec() + ... .with_content_spec() + ... .add_metadata_field("source", str) + ... .with_metadata_spec() + ... .build() + ... ) + """ + def __init__(self): + self._specs: List[SpannerColumnSpec] = [] + + @staticmethod + def with_defaults() -> 'SpannerColumnSpecsBuilder': + """Create builder with default schema. + + Default schema includes: + - id (STRING): Chunk ID + - embedding (ARRAY<FLOAT32>): Dense embedding vector + - content (STRING): Chunk content text + - metadata (JSON): Full metadata as JSON + + Returns: + Builder with default column specifications + """ + return ( + SpannerColumnSpecsBuilder().with_id_spec().with_embedding_spec(). + with_content_spec().with_metadata_spec()) + + def with_id_spec( + self, + column_name: str = "id", + python_type: Type = str, + extract_fn: Optional[Callable[[Chunk], Any]] = lambda chunk: chunk.id, + convert_fn: Optional[Callable[[Any], Any]] = None + ) -> 'SpannerColumnSpecsBuilder': + """Add ID column specification. + + Args: + column_name: Column name (default: "id") + python_type: Python type (default: str) + extract_fn: Value extractor (default: lambda chunk: chunk.id) + convert_fn: Optional converter (e.g., to cast to int) + + Returns: + Self for method chaining + + Examples: + Default string ID: + >>> builder.with_id_spec() + + Integer ID with conversion: + >>> builder.with_id_spec( + ... python_type=int, + ... convert_fn=lambda id: int(id.split('_')[1]) + ... ) + """ + + self._specs.append( + SpannerColumnSpec( + column_name=column_name, + python_type=python_type, + value_fn=functools.partial( + _extract_and_convert, extract_fn, convert_fn))) + return self + + def with_embedding_spec( + self, + column_name: str = "embedding", + extract_fn: Optional[Callable[[Chunk], List[float]]] = None, + convert_fn: Optional[Callable[[List[float]], List[float]]] = None + ) -> 'SpannerColumnSpecsBuilder': + """Add embedding array column (ARRAY<FLOAT32> or ARRAY<FLOAT64>). + + Args: + column_name: Column name (default: "embedding") + extract_fn: Value extractor (default: chunk.embedding.dense_embedding) + convert_fn: Optional converter (e.g., normalize, quantize) + + Returns: + Self for method chaining + + Examples: + Default embedding: + >>> builder.with_embedding_spec() + + Normalized embedding: + >>> def normalize(vec): + ... norm = (sum(x**2 for x in vec) ** 0.5) or 1.0 + ... return [x/norm for x in vec] + >>> builder.with_embedding_spec(convert_fn=normalize) + + Rounded precision: + >>> builder.with_embedding_spec( + ... convert_fn=lambda vec: [round(x, 4) for x in vec] + ... ) + """ + def default_fn(chunk: Chunk) -> List[float]: + if chunk.embedding is None or chunk.embedding.dense_embedding is None: + raise ValueError(f'Chunk must contain embedding: {chunk}') + return chunk.embedding.dense_embedding + + extract_fn = extract_fn or default_fn + + self._specs.append( + SpannerColumnSpec( + column_name=column_name, + python_type=List[float], + value_fn=functools.partial( + _extract_and_convert, extract_fn, convert_fn))) + return self + + def with_content_spec( + self, + column_name: str = "content", + python_type: Type = str, + extract_fn: Optional[Callable[[Chunk], Any]] = None, + convert_fn: Optional[Callable[[Any], Any]] = None + ) -> 'SpannerColumnSpecsBuilder': + """Add content column. + + Args: + column_name: Column name (default: "content") + python_type: Python type (default: str) + extract_fn: Value extractor (default: chunk.content.text) + convert_fn: Optional converter + + Returns: + Self for method chaining + + Examples: + Default text content: + >>> builder.with_content_spec() + + Content length as integer: + >>> builder.with_content_spec( + ... column_name="content_length", + ... python_type=int, + ... convert_fn=lambda text: len(text.split()) + ... ) + + Truncated content: + >>> builder.with_content_spec( + ... convert_fn=lambda text: text[:1000] + ... ) + """ + def default_fn(chunk: Chunk) -> str: + if chunk.content.text is None: + raise ValueError(f'Chunk must contain content: {chunk}') + return chunk.content.text + + extract_fn = extract_fn or default_fn + + self._specs.append( + SpannerColumnSpec( + column_name=column_name, + python_type=python_type, + value_fn=functools.partial( + _extract_and_convert, extract_fn, convert_fn))) + return self + + def with_metadata_spec( + self, + column_name: str = "metadata", + value_fn: Optional[Callable[[Chunk], Any]] = None Review Comment: ```suggestion value_fn: Optional[Callable[[Chunk], str]] = None ``` (I think this has to a string, correct me if I'm wrong) -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected]
