chore: import upstream snapshot with attribution

docs-website/reference_versioned_docs/version-2.26/integrations-api/supabase.md

@@ -0,0 +1,444 @@
+---
+title: "Supabase"
+id: integrations-supabase
+description: "Supabase integration for Haystack"
+slug: "/integrations-supabase"
+---
+
+
+## haystack_integrations.components.downloaders.supabase.supabase_bucket_downloader
+
+### SupabaseBucketDownloader
+
+Downloads files from a Supabase Storage bucket and returns them as ByteStream objects.
+
+Files are downloaded in-memory and returned as `ByteStream` objects ready for further
+processing in indexing pipelines (e.g. passing to a `DocumentConverter`).
+
+Example usage:
+
+```python
+from haystack_integrations.components.downloaders.supabase import SupabaseBucketDownloader
+from haystack.utils import Secret
+
+downloader = SupabaseBucketDownloader(
+    supabase_url="https://<project-ref>.supabase.co",
+    supabase_key=Secret.from_env_var("SUPABASE_SERVICE_KEY"),
+    bucket_name="my-documents",
+)
+result = downloader.run(sources=["reports/report.pdf", "data/notes.txt"])
+streams = result["streams"]
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    supabase_url: str,
+    supabase_key: Secret = Secret.from_env_var("SUPABASE_SERVICE_KEY"),
+    bucket_name: str,
+    file_extensions: list[str] | None = None
+) -> None
+```
+
+Creates a new SupabaseBucketDownloader instance.
+
+**Parameters:**
+
+- **supabase_url** (<code>str</code>) – The URL of your Supabase project, e.g. `https://<project-ref>.supabase.co`.
+- **supabase_key** (<code>Secret</code>) – The Supabase API key used to authenticate requests. Defaults to the
+  `SUPABASE_SERVICE_KEY` environment variable. Use the service role key for private buckets.
+- **bucket_name** (<code>str</code>) – The name of the Supabase Storage bucket to download files from.
+- **file_extensions** (<code>list\[str\] | None</code>) – Optional list of file extensions to filter downloads (e.g. `[".pdf", ".txt"]`).
+  If `None`, all files are downloaded. Extensions are matched case-insensitively.
+
+#### warm_up
+
+```python
+warm_up() -> None
+```
+
+Initializes the Supabase client.
+
+Called automatically on the first run(), or can be called explicitly in a pipeline.
+
+#### run
+
+```python
+run(sources: list[str]) -> dict[str, list[ByteStream]]
+```
+
+Downloads files from the Supabase Storage bucket.
+
+**Parameters:**
+
+- **sources** (<code>list\[str\]</code>) – List of file paths within the bucket to download,
+  e.g. `["folder/file.pdf", "notes.txt"]`.
+
+**Returns:**
+
+- <code>dict\[str, list\[ByteStream\]\]</code> – A dictionary with:
+- `streams`: list of `ByteStream` objects, one per successfully downloaded file.
+  Each `ByteStream` has `meta["file_path"]` and `meta["bucket_name"]` set.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabaseBucketDownloader
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SupabaseBucketDownloader</code> – Deserialized component.
+
+## haystack_integrations.components.retrievers.supabase.embedding_retriever
+
+### SupabasePgvectorEmbeddingRetriever
+
+Bases: <code>PgvectorEmbeddingRetriever</code>
+
+Retrieves documents from the `SupabasePgvectorDocumentStore`, based on their dense embeddings.
+
+This is a thin wrapper around `PgvectorEmbeddingRetriever`, adapted for use with
+`SupabasePgvectorDocumentStore`.
+
+Example usage:
+
+# Set an environment variable `SUPABASE_DB_URL` with the connection string to your Supabase database.
+
+```bash
+export SUPABASE_DB_URL=postgresql://postgres:postgres@localhost:5432/postgres
+```
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.types.policy import DuplicatePolicy
+from haystack.components.embedders import SentenceTransformersTextEmbedder, SentenceTransformersDocumentEmbedder
+
+from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
+from haystack_integrations.components.retrievers.supabase import SupabasePgvectorEmbeddingRetriever
+
+document_store = SupabasePgvectorDocumentStore(
+    embedding_dimension=768,
+    vector_function="cosine_similarity",
+    recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+             Document(content="Elephants have been observed to behave in a way that indicates..."),
+             Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_embedder = SentenceTransformersDocumentEmbedder()
+document_embedder.warm_up()
+documents_with_embeddings = document_embedder.run(documents)
+document_store.write_documents(documents_with_embeddings.get("documents"), policy=DuplicatePolicy.OVERWRITE)
+
+query_pipeline = Pipeline()
+query_pipeline.add_component("text_embedder", SentenceTransformersTextEmbedder())
+query_pipeline.add_component("retriever", SupabasePgvectorEmbeddingRetriever(document_store=document_store))
+query_pipeline.connect("text_embedder.embedding", "retriever.query_embedding")
+
+query = "How many languages are there?"
+
+res = query_pipeline.run({"text_embedder": {"text": query}})
+print(res['retriever']['documents'][0].content)
+# >> "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: SupabasePgvectorDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    vector_function: (
+        Literal["cosine_similarity", "inner_product", "l2_distance"] | None
+    ) = None,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the SupabasePgvectorEmbeddingRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>SupabasePgvectorDocumentStore</code>) – An instance of `SupabasePgvectorDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance'] | None</code>) – The similarity function to use when searching for similar embeddings.
+  Defaults to the one set in the `document_store` instance.
+  `"cosine_similarity"` and `"inner_product"` are similarity functions and
+  higher scores indicate greater similarity between the documents.
+  `"l2_distance"` returns the straight-line distance between vectors,
+  and the most similar documents are the ones with the smallest score.
+  **Important**: if the document store is using the `"hnsw"` search strategy, the vector function
+  should match the one utilized during index creation to take advantage of the index.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `SupabasePgvectorDocumentStore` or if
+  `vector_function` is not one of the valid options.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorEmbeddingRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SupabasePgvectorEmbeddingRetriever</code> – Deserialized component.
+
+## haystack_integrations.components.retrievers.supabase.keyword_retriever
+
+### SupabasePgvectorKeywordRetriever
+
+Bases: <code>PgvectorKeywordRetriever</code>
+
+Retrieves documents from the `SupabasePgvectorDocumentStore`, based on keywords.
+
+This is a thin wrapper around `PgvectorKeywordRetriever`, adapted for use with
+`SupabasePgvectorDocumentStore`.
+
+To rank the documents, the `ts_rank_cd` function of PostgreSQL is used.
+It considers how often the query terms appear in the document, how close together the terms are in the document,
+and how important is the part of the document where they occur.
+
+Example usage:
+
+# Set an environment variable `SUPABASE_DB_URL` with the connection string to your Supabase database.
+
+```bash
+export SUPABASE_DB_URL=postgresql://postgres:postgres@localhost:5432/postgres
+```
+
+```python
+from haystack import Document, Pipeline
+from haystack.document_stores.types.policy import DuplicatePolicy
+
+from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
+from haystack_integrations.components.retrievers.supabase import SupabasePgvectorKeywordRetriever
+
+document_store = SupabasePgvectorDocumentStore(
+    embedding_dimension=768,
+    recreate_table=True,
+)
+
+documents = [Document(content="There are over 7,000 languages spoken around the world today."),
+             Document(content="Elephants have been observed to behave in a way that indicates..."),
+             Document(content="In certain places, you can witness the phenomenon of bioluminescent waves.")]
+
+document_store.write_documents(documents, policy=DuplicatePolicy.OVERWRITE)
+retriever = SupabasePgvectorKeywordRetriever(document_store=document_store)
+result = retriever.run(query="languages")
+
+print(result['documents'][0].content)
+# >> "There are over 7,000 languages spoken around the world today."
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    document_store: SupabasePgvectorDocumentStore,
+    filters: dict[str, Any] | None = None,
+    top_k: int = 10,
+    filter_policy: str | FilterPolicy = FilterPolicy.REPLACE
+) -> None
+```
+
+Initialize the SupabasePgvectorKeywordRetriever.
+
+**Parameters:**
+
+- **document_store** (<code>SupabasePgvectorDocumentStore</code>) – An instance of `SupabasePgvectorDocumentStore`.
+- **filters** (<code>dict\[str, Any\] | None</code>) – Filters applied to the retrieved Documents.
+- **top_k** (<code>int</code>) – Maximum number of Documents to return.
+- **filter_policy** (<code>str | FilterPolicy</code>) – Policy to determine how filters are applied.
+
+**Raises:**
+
+- <code>ValueError</code> – If `document_store` is not an instance of `SupabasePgvectorDocumentStore`.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorKeywordRetriever
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SupabasePgvectorKeywordRetriever</code> – Deserialized component.
+
+## haystack_integrations.document_stores.supabase.document_store
+
+### SupabasePgvectorDocumentStore
+
+Bases: <code>PgvectorDocumentStore</code>
+
+A Document Store for Supabase, using PostgreSQL with the pgvector extension.
+
+It should be used with Supabase installed.
+
+This is a thin wrapper around `PgvectorDocumentStore` with Supabase-specific defaults:
+
+- Reads the connection string from the `SUPABASE_DB_URL` environment variable.
+- Defaults `create_extension` to `False` since pgvector is pre-installed on Supabase.
+
+**Connection notes:** Supabase offers two pooler ports — transaction mode (6543) and session mode (5432).
+For best compatibility with pgvector operations, use session mode (port 5432) or a direct connection.
+
+Example usage:
+
+# Set an environment variable `SUPABASE_DB_URL` with the connection string to your Supabase database.
+
+```bash
+export SUPABASE_DB_URL=postgresql://postgres:postgres@localhost:5432/postgres
+```
+
+```python
+from haystack_integrations.document_stores.supabase import SupabasePgvectorDocumentStore
+
+document_store = SupabasePgvectorDocumentStore(
+    embedding_dimension=768,
+    vector_function="cosine_similarity",
+    recreate_table=True,
+)
+```
+
+#### __init__
+
+```python
+__init__(
+    *,
+    connection_string: Secret = Secret.from_env_var("SUPABASE_DB_URL"),
+    create_extension: bool = False,
+    schema_name: str = "public",
+    table_name: str = "haystack_documents",
+    language: str = "english",
+    embedding_dimension: int = 768,
+    vector_type: Literal["vector", "halfvec"] = "vector",
+    vector_function: Literal[
+        "cosine_similarity", "inner_product", "l2_distance"
+    ] = "cosine_similarity",
+    recreate_table: bool = False,
+    search_strategy: Literal[
+        "exact_nearest_neighbor", "hnsw"
+    ] = "exact_nearest_neighbor",
+    hnsw_recreate_index_if_exists: bool = False,
+    hnsw_index_creation_kwargs: dict[str, int] | None = None,
+    hnsw_index_name: str = "haystack_hnsw_index",
+    hnsw_ef_search: int | None = None,
+    keyword_index_name: str = "haystack_keyword_index"
+) -> None
+```
+
+Creates a new SupabasePgvectorDocumentStore instance.
+
+**Parameters:**
+
+- **connection_string** (<code>Secret</code>) – The connection string for the Supabase PostgreSQL database, defined as an
+  environment variable. Default: `SUPABASE_DB_URL`. Format:
+  `postgresql://postgres.[project-ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres`
+- **create_extension** (<code>bool</code>) – Whether to create the pgvector extension if it doesn't exist.
+  Defaults to `False` since Supabase has pgvector pre-installed.
+- **schema_name** (<code>str</code>) – The name of the schema the table is created in.
+- **table_name** (<code>str</code>) – The name of the table to use to store Haystack documents.
+- **language** (<code>str</code>) – The language to be used to parse query and document content in keyword retrieval.
+- **embedding_dimension** (<code>int</code>) – The dimension of the embedding.
+- **vector_type** (<code>Literal['vector', 'halfvec']</code>) – The type of vector used for embedding storage. `"vector"` or `"halfvec"`.
+- **vector_function** (<code>Literal['cosine_similarity', 'inner_product', 'l2_distance']</code>) – The similarity function to use when searching for similar embeddings.
+- **recreate_table** (<code>bool</code>) – Whether to recreate the table if it already exists.
+- **search_strategy** (<code>Literal['exact_nearest_neighbor', 'hnsw']</code>) – The search strategy to use: `"exact_nearest_neighbor"` or `"hnsw"`.
+- **hnsw_recreate_index_if_exists** (<code>bool</code>) – Whether to recreate the HNSW index if it already exists.
+- **hnsw_index_creation_kwargs** (<code>dict\[str, int\] | None</code>) – Additional keyword arguments for HNSW index creation.
+- **hnsw_index_name** (<code>str</code>) – Index name for the HNSW index.
+- **hnsw_ef_search** (<code>int | None</code>) – The `ef_search` parameter to use at query time for HNSW.
+- **keyword_index_name** (<code>str</code>) – Index name for the Keyword index.
+
+#### to_dict
+
+```python
+to_dict() -> dict[str, Any]
+```
+
+Serializes the component to a dictionary.
+
+**Returns:**
+
+- <code>dict\[str, Any\]</code> – Dictionary with serialized data.
+
+#### from_dict
+
+```python
+from_dict(data: dict[str, Any]) -> SupabasePgvectorDocumentStore
+```
+
+Deserializes the component from a dictionary.
+
+**Parameters:**
+
+- **data** (<code>dict\[str, Any\]</code>) – Dictionary to deserialize from.
+
+**Returns:**
+
+- <code>SupabasePgvectorDocumentStore</code> – Deserialized component.