cocoindex 0.2.10__tar.gz → 0.2.11__tar.gz

{cocoindex-0.2.10 → cocoindex-0.2.11}/.github/workflows/_docs_release.yml

@@ -3,6 +3,10 @@ name: Release Docs (INTERNAL)
 on:
   workflow_call:
 
+permissions:
+  contents: read
+  pages: write
+
 jobs:
   deploy:
     runs-on: ubuntu-latest

{cocoindex-0.2.10 → cocoindex-0.2.11}/.github/workflows/_test.yml

@@ -3,6 +3,9 @@ name: Run Tests (INTERNAL)
 on:
     workflow_call:
 
+permissions:
+  contents: read
+
 env:
   CARGO_TERM_COLOR: always
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/.github/workflows/docs_release.yml

@@ -5,6 +5,7 @@ on:
 
 permissions:
   contents: write
+  pages: write
 
 jobs:
   deploy:

{cocoindex-0.2.10 → cocoindex-0.2.11}/.github/workflows/docs_test.yml

@@ -7,6 +7,9 @@ on:
       - docs/**
       - ".github/workflows/docs_test.yml"
 
+permissions:
+  contents: read
+
 jobs:
   test-deploy:
     runs-on: ubuntu-latest

{cocoindex-0.2.10 → cocoindex-0.2.11}/.github/workflows/release.yml

@@ -12,6 +12,7 @@ on:
 
 permissions:
   contents: read
+  pages: write
 
 jobs:
   create-versioned-toml:

{cocoindex-0.2.10 → cocoindex-0.2.11}/Cargo.lock

@@ -1283,7 +1283,7 @@ dependencies = [
 
 [[package]]
 name = "cocoindex"
-version = "0.2.10"
+version = "0.2.11"
 dependencies = [
  "anyhow",
  "async-openai",

{cocoindex-0.2.10 → cocoindex-0.2.11}/Cargo.toml

@@ -2,7 +2,7 @@
 name = "cocoindex"
 # Version used for local development is always higher than others to take precedence.
 # Will be overridden for specific release versions.
-version = "0.2.10"
+version = "0.2.11"
 edition = "2024"
 rust-version = "1.88"
 license = "Apache-2.0"

{cocoindex-0.2.10 → cocoindex-0.2.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cocoindex
-Version: 0.2.10
+Version: 0.2.11
 Classifier: Development Status :: 3 - Alpha
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: OS Independent

{cocoindex-0.2.10 → cocoindex-0.2.11}/THIRD_PARTY_NOTICES.html

@@ -2428,7 +2428,7 @@ Software.
                 <h3 id="Apache-2.0">Apache License 2.0</h3>
                 <h4>Used by:</h4>
                 <ul class="license-used-by">
-                    <li><a href=" https://crates.io/crates/cocoindex ">cocoindex 0.2.10</a></li>
+                    <li><a href=" https://crates.io/crates/cocoindex ">cocoindex 0.2.11</a></li>
                     <li><a href=" https://github.com/awesomized/crc-fast-rust ">crc-fast 1.3.0</a></li>
                     <li><a href=" https://github.com/qdrant/rust-client ">qdrant-client 1.15.0</a></li>
                 </ul>

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/academic_papers_index.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/academic_papers_index'
 sidebar_custom_props:
   image: /img/examples/academic_papers_index/cover.png
   tags: [vector-index, metadata]
+image: /img/examples/academic_papers_index/cover.png
 tags: [vector-index, metadata]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/codebase_index.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/code_index'
 sidebar_custom_props:
   image: /img/examples/codebase_index/cover.png
   tags: [vector-index, codebase]
+image: /img/examples/codebase_index/cover.png
 tags: [vector-index, codebase]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/custom_targets.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/custom_targets'
 sidebar_custom_props:
   image: /img/examples/custom_targets/cover.png
   tags: [custom-building-blocks]
+image: /img/examples/custom_targets/cover.png
 tags: [custom-building-blocks]
 ---
 import { GitHubButton, YouTubeButton, DocumentationButton } from '../../../src/components/GitHubButton';

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/docs_to_knowledge_graph.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/knowledge-graph-for-docs'
 sidebar_custom_props:
   image: /img/examples/docs_to_knowledge_graph/cover.png
   tags: [knowledge-graph, structured-data-extraction]
+image: /img/examples/docs_to_knowledge_graph/cover.png
 tags: [knowledge-graph, structured-data-extraction]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/document_ai.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/document_ai'
 sidebar_custom_props:
   image: /img/examples/document_ai/cover.png
   tags: [vector-index, custom-building-block]
+image: /img/examples/document_ai/cover.png
 tags: [vector-index, custom-building-block]
 ---
 import { GitHubButton, DocumentationButton, ExampleButton } from '../../../src/components/GitHubButton';

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/image_search.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/image_search'
 sidebar_custom_props:
   image: /img/examples/image_search/cover.png
   tags: [vector-index, multi-modal]
+image: /img/examples/image_search/cover.png
 tags: [vector-index, multi-modal]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/manual_extraction.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/manual_extraction'
 sidebar_custom_props:
   image: /img/examples/manual_extraction/cover.png
   tags: [structured-data-extraction, data-mapping]
+image: /img/examples/manual_extraction/cover.png
 tags: [structured-data-extraction, data-mapping]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/multi_format_index.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/multi_format_index'
 sidebar_custom_props:
   image: /img/examples/multi_format_index/cover.png
   tags: [vector-index, multi-modal]
+image: /img/examples/multi_format_index/cover.png
 tags: [vector-index, multi-modal]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/patient_form_extraction.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/patient_form_extraction'
 sidebar_custom_props:
   image: /img/examples/patient_form_extraction/cover.png
   tags: [structured-data-extraction, data-mapping ]
+image: /img/examples/patient_form_extraction/cover.png
 tags: [structured-data-extraction, data-mapping]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/photo_search.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/photo_search'
 sidebar_custom_props:
   image: /img/examples/photo_search/cover.png
   tags: [vector-index, multi-modal]
+image: /img/examples/photo_search/cover.png
 tags: [vector-index, multi-modal]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/postgres_source.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/postgres_source'
 sidebar_custom_props:
   image: /img/examples/postgres_source/cover.png
   tags: [data-mapping, vector-index, postgres]
+image: /img/examples/postgres_source/cover.png
 tags: [data-mapping, vector-index, postgres]
 ---
 import { GitHubButton, YouTubeButton, DocumentationButton } from '../../../src/components/GitHubButton';

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/product_recommendation.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/product_recommendation'
 sidebar_custom_props:
   image: /img/examples/product_recommendation/cover.png
   tags: [knowledge-graph ]
+image: /img/examples/product_recommendation/cover.png
 tags: [knowledge-graph]
 ---
 

{cocoindex-0.2.10 → cocoindex-0.2.11}/docs/docs/examples/examples/simple_vector_index.md

@@ -7,6 +7,7 @@ canonicalUrl: '/examples/simple_vector_index'
 sidebar_custom_props:
   image: /img/examples/simple_vector_index/cover.png
   tags: [vector-index]
+image: /img/examples/simple_vector_index/cover.png
 tags: [vector-index]
 ---
 

cocoindex-0.2.11/docs/docs/query.mdx

@@ -0,0 +1,213 @@
+---
+title: Query Support
+description: CocoIndex supports vector search and text search.
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# CocoIndex Query Support
+
+The main functionality of CocoIndex is indexing.
+The goal of indexing is to enable efficient querying against your data.
+You can use any libraries or frameworks of your choice to perform queries.
+At the same time, CocoIndex provides seamless integration between indexing and querying workflows.
+
+*   You can share transformations between indexing and querying.
+*   You can define query handlers, so that you can easily run queries in tools like CocoInsight.
+*   You can easily retrieve table names when using CocoIndex's default naming conventions.
+
+## Transform Flow
+
+Sometimes a part of the transformation logic needs to be shared between indexing and querying,
+e.g. when we build a vector index and query against it, the embedding computation needs to be consistent between indexing and querying.
+
+In this case, you can:
+
+1.  Extract a sub-flow with the shared transformation logic into a standalone function.
+    *   It takes one or more data slices as input.
+    *   It returns one data slice as output.
+    *   You need to annotate data types for both inputs and outputs as type parameter for `cocoindex.DataSlice[T]`. See [data types](./core/data_types.mdx) for more details about supported data types.
+
+2.  When you're defining your indexing flow, you can directly call the function.
+    The body will be executed, so that the transformation logic will be added as part of the indexing flow.
+
+3.  At query time, you usually want to directly run the function with specific input data, instead of letting it called as part of a long-lived indexing flow.
+    To do this, declare the function as a *transform flow*, by decorating it with `@cocoindex.transform_flow()`.
+    This will add `eval()` and `eval_async()` methods to the function, so that you can directly call with specific input data.
+
+
+<Tabs>
+<TabItem value="python" label="Python">
+
+For example, based on the flow in [quickstart](getting_started/quickstart), you can extract the invocation of `SentenceTransformerEmbed` into a standalone function:
+
+```python
+@cocoindex.transform_flow()
+def text_to_embedding(text: cocoindex.DataSlice[str]) -> cocoindex.DataSlice[NDArray[np.float32]]:
+    return text.transform(
+        cocoindex.functions.SentenceTransformerEmbed(
+            model="sentence-transformers/all-MiniLM-L6-v2"))
+```
+
+When you're defining your indexing flow, you can directly call the function:
+
+```python
+with doc["chunks"].row() as chunk:
+    chunk["embedding"] = text_to_embedding(chunk["text"])
+```
+
+or, using the `call()` method of the transform flow on the first argument, to make operations chainable:
+
+```python
+with doc["chunks"].row() as chunk:
+    chunk["embedding"] = chunk["text"].call(text_to_embedding)
+```
+
+Any time, you can call the `eval()` method with specific string, which will return a `NDArray[np.float32]`:
+
+```python
+print(text_to_embedding.eval("Hello, world!"))
+```
+
+If you're in an async context, please call the `eval_async()` method instead:
+
+```python
+print(await text_to_embedding.eval_async("Hello, world!"))
+```
+
+</TabItem>
+</Tabs>
+
+## Query Handler
+
+Query handlers let you expose a simple function that takes a query string and returns structured results. They are discoverable by tools like CocoInsight so you can query your indexes without writing extra glue code.
+
+- **What you write**: a plain Python function `def search(query: str) -> cocoindex.QueryOutput`.
+- **How you register**: decorate it with `@<your_flow>.query_handler(...)` or call `flow.add_query_handler(...)` directly.
+- **What you return**: a `cocoindex.QueryOutput(results=[...], query_info=...)`.
+- **Optional metadata**: `QueryHandlerResultFields` tells tools which fields contain the embedding vector and score.
+
+### Minimum Query Handler
+
+A minimum query handler looks like this:
+
+<Tabs>
+<TabItem value="python" label="Python">
+
+```python
+@my_flow.query_handler(name="run_query")  # Name is optional, use the function name by default
+def run_query(query: str) -> cocoindex.QueryOutput:
+    # 1) Perform your query against the input `query`
+    ...
+
+    # 2) Return structured results
+    return cocoindex.QueryOutput(results=[{"filename": "...", "text": "..."}])
+```
+
+</TabItem>
+</Tabs>
+
+Notes about the decorator:
+
+- The handler can be sync or async.
+- The decorator registers the handler as a query handler for the flow. It doesn't change the function signature: you can still call the function directly.
+
+Your function returns a `cocoindex.QueryOutput`, with a `results` field, which is a list of dicts (or dataclass instances) representing query results.
+Each element is a query result. All data types convertible to JSON are supported. Embeddings can be `list[float]` or numpy array.
+
+A simple query handler like this will enable CocoInsight to display the query results for you to view easily.
+
+### Query Handler with Additional Information
+
+You can provide additional information by extra fields like this:
+
+<Tabs>
+<TabItem value="python" label="Python">
+
+```python
+@my_flow.query_handler(
+    name="run_query",  # Name is optional, use the function name by default
+    result_fields=cocoindex.QueryHandlerResultFields(
+        embedding=["embedding"],  # path to the vector field in each result
+        score="score",            # numeric similarity score (higher is better)
+    )
+)
+def run_query(query: str) -> cocoindex.QueryOutput:
+    # 1) Compute embedding for the input query (often via a transform flow)
+    query_vector = text_to_embedding.eval(query)
+
+    # 2) Run your database/vector store query
+    ...
+
+    # 3) Return structured results plus optional query_info
+    return cocoindex.QueryOutput(
+        results=[{"text": "...", "embedding": some_vec, "score": 0.92}],
+        query_info=cocoindex.QueryInfo(
+            embedding=query_vector,
+            similarity_metric=cocoindex.VectorSimilarityMetric.COSINE_SIMILARITY,
+        ),
+    )
+```
+
+</TabItem>
+</Tabs>
+
+- `result_fields` within `query_handler` specifies field names in the query results returned by the query handler. This provides metadata for tools like CocoInsight to recognize structure of the query results, as specified by the following fields (all optional):
+    - `embedding` is a list of keys that navigates to the embedding in each result (use multiple in case of multiple embeddings, e.g. using different models).
+    - `score` should point to a numeric field where larger means more relevant.
+
+- `QueryOutput.query_info` specifies information for the query itself, with the following fields (all optional):
+    - `embedding` is the embedding of the query.
+    - `similarity_metric` is the similarity metric used to query the index.
+
+
+### Directly Register without Decorator
+
+The above example can be written without decorator like this:
+
+```python
+def my_search(query: str) -> cocoindex.QueryOutput:
+    ...
+
+my_flow.add_query_handler(
+    name="run_query",
+    handler=my_search,
+    result_fields=cocoindex.QueryHandlerResultFields(embedding=["embedding"], score="score"),
+)
+```
+
+Sometimes this provides more flexibility.
+
+### Examples
+
+You can see our following examples:
+
+- [Text Embedding (PostgreSQL)](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding/main.py)
+- [Text Embedding (Qdrant)](https://github.com/cocoindex-io/cocoindex/blob/main/examples/text_embedding_qdrant/main.py)
+- [Code Embedding](https://github.com/cocoindex-io/cocoindex/blob/main/examples/code_embedding/main.py)
+
+
+## Get Target Native Names
+
+In your indexing flow, when you export data to a target, you can specify the target name (e.g. a database table name, a collection name, the node label in property graph databases, etc.) explicitly,
+or for some backends you can also omit it and let CocoIndex generate a default name for you.
+For the latter case, CocoIndex provides a utility function `cocoindex.utils.get_target_default_name()` to get the default name.
+It takes the following arguments:
+
+*   `flow` (type: `cocoindex.Flow`): The flow to get the default name for.
+*   `target_name` (type: `str`): The export target name, appeared in the `export()` call.
+
+For example:
+
+<Tabs>
+<TabItem value="python" label="Python">
+
+```python
+table_name = cocoindex.utils.get_target_default_name(text_embedding_flow, "doc_embeddings")
+query = f"SELECT filename, text FROM {table_name} ORDER BY embedding <=> %s DESC LIMIT 5"
+...
+```
+
+</TabItem>
+</Tabs>