cocoindex 0.2.9__tar.gz → 0.2.11__tar.gz

{cocoindex-0.2.9 → 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.9 → 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.9 → cocoindex-0.2.11}/.github/workflows/docs_release.yml

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

{cocoindex-0.2.9 → 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.9 → 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.9 → cocoindex-0.2.11}/.pre-commit-config.yaml

@@ -49,7 +49,7 @@ repos:
 
         - id: mypy-check
           name: mypy type check
-          entry: mypy
+          entry: mypy --cache-fine-grain
           language: system
           types: [python]
           pass_filenames: false

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

@@ -1283,7 +1283,7 @@ dependencies = [
 
 [[package]]
 name = "cocoindex"
-version = "0.2.9"
+version = "0.2.11"
 dependencies = [
  "anyhow",
  "async-openai",
@@ -1367,6 +1367,7 @@ dependencies = [
  "tree-sitter-rust",
  "tree-sitter-scala",
  "tree-sitter-sequel",
+ "tree-sitter-solidity",
  "tree-sitter-swift",
  "tree-sitter-toml-ng",
  "tree-sitter-typescript",
@@ -5904,6 +5905,16 @@ dependencies = [
  "tree-sitter-language",
 ]
 
+[[package]]
+name = "tree-sitter-solidity"
+version = "1.2.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4eacf8875b70879f0cb670c60b233ad0b68752d9e1474e6c3ef168eea8a90b25"
+dependencies = [
+ "cc",
+ "tree-sitter-language",
+]
+
 [[package]]
 name = "tree-sitter-swift"
 version = "0.7.1"

{cocoindex-0.2.9 → 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.9"
+version = "0.2.11"
 edition = "2024"
 rust-version = "1.88"
 license = "Apache-2.0"
@@ -101,6 +101,7 @@ tree-sitter-toml-ng = "0.7.0"
 tree-sitter-typescript = "0.23.2"
 tree-sitter-xml = "0.7.0"
 tree-sitter-yaml = "0.7.1"
+tree-sitter-solidity = "1.2.13"
 
 globset = "0.4.16"
 unicase = "2.8.1"

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

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

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

@@ -45,7 +45,7 @@
         <h2>Overview of licenses:</h2>
         <ul class="licenses-overview">
             <li><a href="#Apache-2.0">Apache License 2.0</a> (412)</li>
-            <li><a href="#MIT">MIT License</a> (124)</li>
+            <li><a href="#MIT">MIT License</a> (125)</li>
             <li><a href="#Unicode-3.0">Unicode License v3</a> (19)</li>
             <li><a href="#ISC">ISC License</a> (8)</li>
             <li><a href="#BSD-3-Clause">BSD 3-Clause &quot;New&quot; or &quot;Revised&quot; License</a> (6)</li>
@@ -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.9</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>
@@ -11376,6 +11376,20 @@ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
 IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 DEALINGS IN THE SOFTWARE.
 </pre>
+            </li>
+            <li class="license">
+                <h3 id="MIT">MIT License</h3>
+                <h4>Used by:</h4>
+                <ul class="license-used-by">
+                    <li><a href=" https://github.com/JoranHonig/tree-sitter-solidity ">tree-sitter-solidity 1.2.13</a></li>
+                </ul>
+                <pre class="license-text">Copyright (c) 2020 Joran Honig
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &quot;Software&quot;), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED &quot;AS IS&quot;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</pre>
             </li>
             <li class="license">
                 <h3 id="MIT">MIT License</h3>

{cocoindex-0.2.9 → cocoindex-0.2.11}/docs/docs/core/settings.mdx

@@ -10,49 +10,82 @@ import TabItem from '@theme/TabItem';
 
 Certain settings need to be provided for CocoIndex to work, e.g. database connections, app namespace, etc.
 
-## Launch CocoIndex
+## Configure CocoIndex Settings
 
-You have two ways to launch CocoIndex:
+Note that in general, you have two ways to launch CocoIndex:
 
+*   Call CocoIndex APIs from your own Python application or library.
 *   Use [Cocoindex CLI](cli). It's handy for most routine indexing building and management tasks.
-    It will load settings from environment variables, either already set in your environment, or specified in `.env` file.
-    See [CLI](cli#environment-variables) for more details.
 
-*   Call CocoIndex functionality from your own Python application or library.
-    It's needed when you want to leverage CocoIndex support for query, or have your custom logic to trigger indexing, etc.
 
-    <Tabs>
-    <TabItem value="python" label="Python" default>
+CocoIndex exposes process-level settings specified by `cocoindex.Settings` dataclass.
+Settings can be configured in three different ways.
+In the following sections, the later ones will override the earlier ones.
 
-    You need to explicitly call `cocoindex.init()` before doing anything with CocoIndex, and settings will be loaded during the call.
+### Environment Variables
 
-    *   If it's called without any argument, it will load settings from environment variables.
-        Only existing environment variables already set in your environment will be used.
-        If you want to load environment variables from a specific `.env` file, consider call `load_dotenv()` provided by the [`python-dotenv`](https://github.com/theskumar/python-dotenv) package.
+The simplest approach is to set corresponding environment variables.
+See [List of Environment Variables](#list-of-environment-variables) for specific environment variables.
 
-        ```py
-        from dotenv import load_dotenv
-        import cocoindex
+:::tip
 
-        load_dotenv()
-        cocoindex.init()
-        ```
+You can consider place a `.env` file in your directory.
+The [CLI](cli#environment-variables) will load environment variables from the `.env` file (see [CLI](cli#environment-variables) for more details).
+From your own main module, you can also load environment variables with a package like [`python-dotenv`](https://github.com/theskumar/python-dotenv).
 
-    *   It takes an optional `cocoindex.Settings` dataclass object as argument, so you can also construct settings explicitly and pass to it:
+:::
+
+### Setting Function
+
+A more flexible approach is to provide a setting function that returns a `cocoindex.Settings` dataclass object.
+The setting function can have any name, and needs to be decorated with the `@cocoindex.settings` decorator, for example:
+
+```py
+@cocoindex.settings
+def cocoindex_settings() -> cocoindex.Settings:
+    return cocoindex.Settings(
+        database=cocoindex.DatabaseConnectionSpec(
+            url="postgres://cocoindex:cocoindex@localhost/cocoindex"
+        )
+    )
+```
+
+This setting function will be called once when CocoIndex is initialized.
+Once the settings function is provided, environment variables will be ignored.
 
-        ```py
-        import cocoindex
+### `cocoindex.init()` function
 
-        cocoindex.init(
-            cocoindex.Settings(
-                database=cocoindex.DatabaseConnectionSpec(
-                    url="postgres://cocoindex:cocoindex@localhost/cocoindex"
-                )
-            )
+You can also call `cocoindex.init()` with a `cocoindex.Settings` dataclass object as argument, for example:
+
+```py
+cocoindex.init(
+    cocoindex.Settings(
+        database=cocoindex.DatabaseConnectionSpec(
+            url="postgres://cocoindex:cocoindex@localhost/cocoindex"
         )
-        ```
-    </TabItem>
-    </Tabs>
+    )
+)
+```
+
+For example, you can call it in the main function of your application.
+Once the `cocoindex.init()` is called with a `cocoindex.Settings` dataclass object as argument, the `@cocoindex.settings` function and environment variables will be ignored.
+
+This is more flexible, as you can more easily construct `cocoindex.Settings` based on other stuffs you loaded earlier.
+But be careful that if you call `cocoindex.init()` only under the path of main (e.g. within `if __name__ == "__main__":` guard), it won't be executed when you're using CocoIndex CLI, as it won't execute your main logic.
+
+:::info
+
+`cocoindex.init()` is optional:
+
+-   You can call `cocoindex.init()` with a `cocoindex.Settings` dataclass object as argument, or without any argument.
+    When without argument, the settings will be loaded from the `@cocoindex.settings` function or environment variables.
+
+-   You don't have to explicitly call `cocoindex.init()`.
+    CocoIndex will be automatically initialized when needed, e.g. when any method of any flow is called the first time.
+    But calling `cocoindex.init()` explicitly (usually at startup time, e.g. in the main function of your application) has the benefit of making sure CocoIndex library is initialized and any potential exceptions are raised earlier before proceeding with the application.
+    If you need this clarity, you can call it explicitly even if you don't want to provide settings by the `cocoindex.init()` call.
+
+:::
 
 ## List of Settings
 

{cocoindex-0.2.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → 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.9 → cocoindex-0.2.11}/docs/docs/ops/functions.md

@@ -102,6 +102,7 @@ Currently, `SplitRecursively` supports the following languages:
 | Ruby | | `.rb` |
 | Rust | RS | `.rs` |
 | Scala | | `.scala` |
+| Solidity | | `.sol` |
 | SQL | | `.sql` |
 | Swift | | `.swift` |
 | TOML | | `.toml` |

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>