docs(types): update docs for data type

Author: badmonster0

docs/docs/core/custom_function.mdx

@@ -33,7 +33,7 @@ Notes:
 
 *   The `cocoindex.op.function()` function decorator also takes optional parameters.
     See [Parameters for custom functions](#parameters-for-custom-functions) for details.
-*   Types of arugments and the return value must be annotated, so that CocoIndex will have information about data types of the operation's output fields.
+*   Types of arguments and the return value must be annotated, so that CocoIndex will have information about data types of the operation's output fields.
     See [Data Types](/docs/core/data_types) for supported types.
 
 </TabItem>

docs/docs/core/data_types.mdx

@@ -9,36 +9,49 @@ In CocoIndex, all data processed by the flow have a type determined when the flo
 
 This makes schema of data processed by CocoIndex clear, and easily determine the schema of your index.
 
-## Data Types 
+## Data Types
+
+You don't need to spell out data types in CocoIndex, when you define the flow using existing operations (source, function, etc).
+These operations decide data types of fields produced by them based on the spec and input data types.
+All you need to do is to make sure the data passed to functions and storage targets are accepted by them.
+
+When you define [custom functions](/docs/core/custom_function), you need to specify the data types of arguments and return values.
 
 ### Basic Types
 
 This is the list of all basic types supported by CocoIndex:
 
-| Type | Description |Type in Python | Original Type in Python |
+| Type | Description | Specific Python Type | Native Python Type |
 |------|-------------|---------------|-------------------------|
 | Bytes | | `bytes` | `bytes` |
 | Str | | `str` | `str` |
 | Bool | | `bool` | `bool` |
 | Int64 | | `int` | `int` |
-| Float32 | | `cocoindex.typing.Float32` |`float` | 
-| Float64 | |  `cocoindex.typing.Float64` |`float` |
-| Range | | `cocoindex.typing.Range`  | `tuple[int, int]` |
+| Float32 | | `cocoindex.Float32` |`float` | 
+| Float64 | |  `cocoindex.Float64` |`float` |
+| Range | | `cocoindex.Range`  | `tuple[int, int]` |
 | Uuid | | `uuid.UUId` | `uuid.UUID` |
 | Date | | `datetime.date` | `datetime.date` |
 | Time | | `datetime.time` | `datetime.time` |
-| LocalDatetime | Date and time without timezone | `cocoindex.typing.LocalDateTime` | `datetime.datetime` |
-| OffsetDatetime | Date and time with a timezone offset | `cocoindex.typing.OffsetDateTime` | `datetime.datetime` |
-| Vector[*type*, *N*?] | |`Annotated[list[type], cocoindex.typing.Vector(dim=N)]` | `list[type]` | 
-| Json | | `cocoindex.typing.Json` | Any type convertible to JSON by `json` package | 
+| LocalDatetime | Date and time without timezone | `cocoindex.LocalDateTime` | `datetime.datetime` |
+| OffsetDatetime | Date and time with a timezone offset | `cocoindex.OffsetDateTime` | `datetime.datetime` |
+| Vector[*T*, *Dim*?] | *T* must be basic type. *Dim* is a positive integer and optional. |`cocoindex.Vector[T]` or `cocoindex.Vector[T, Dim]` | `list[T]` | 
+| Json | | `cocoindex.Json` | Any data convertible to JSON by `json` package | 
+
+Values of all data types can be represented by values in Python's native types (as described under the Native Python Type column).
+However, the underlying execution engine and some storage system (like Postgres) has finer distinctions for some types, specifically:
 
-For some types, CocoIndex Python SDK provides annotated types with finer granularity than Python's original type, e.g.
 *   *Float32* and *Float64* for `float`, with different precision.
 *   *LocalDateTime* and *OffsetDateTime* for `datetime.datetime`, with different timezone awareness.
-*   *Vector* has dimension information.
+*   *Vector* has optional dimension information.
+*   *Range* and *Json* provide a clear tag for the type, to clearly distinguish the type in CocoIndex.
 
-When defining [custom functions](/docs/core/custom_function), use the specific types as type annotations for arguments and return values.
-So CocoIndex will have information about the specific type.
+The native Python type is always more permissive and can represent a superset of possible values.
+*   Only when you annotate the return type of a custom function, you should use the specific type,
+    so that CocoIndex will have information about the precise type to be used in the execution engine and storage system.
+*   For all other purposes, e.g. to provide annotation for argument types of a custom function, or used internally in your custom function,
+    you can choose whatever to use.
+    The native Python type is usually simpler.
 
 ### Struct Type
 
@@ -94,9 +107,7 @@ LTable is a Table type whose row order is preserved. LTable has no key column.
 In Python, a LTable type is represented by `list[R]`, where `R` is a dataclass representing a row.
 For example, you can use `list[Person]` to represent a LTable with 3 columns: `first_name` (Str), `last_name` (Str), `dob` (Date).
 
-## Index Types
-
-### Key Types
+## Key Types
 
 Currently, the following types are key types
 
@@ -108,16 +119,3 @@ Currently, the following types are key types
 - Uuid
 - Date
 - Struct with all fields being key types
-
-### Vector Type
-
-Users can create vector index on fields with `vector` types.
-A vector index also needs to be configured with a similarity metric, and the index is only effective when this metric is used during retrieval.
-
-Following metrics are supported:
-
-| Metric Name | Description | Similarity Order |
-|-------------|-------------|------------------|
-| CosineSimilarity | [Cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity) | Larger is more similar |
-| L2Distance | [L2 distance (a.k.a. Euclidean distance)](https://en.wikipedia.org/wiki/Euclidean_distance) | Smaller is more similar |
-| InnerProduct | [Inner product](https://en.wikipedia.org/wiki/Inner_product_space) | Larger is more similar |

docs/docs/core/flow_def.mdx

@@ -1,6 +1,7 @@
 ---
 title: Flow Definition
 description: Define a CocoIndex flow, by specifying source, transformations and storages, and connect input/output data of them.
+toc_max_heading_level: 4
 ---
 
 import Tabs from '@theme/Tabs';
@@ -281,16 +282,32 @@ The target storage is managed by CocoIndex, i.e. it'll be created by [CocoIndex
 The `name` for the same storage should remain stable across different runs.
 If it changes, CocoIndex will treat it as an old storage removed and a new one created, and perform setup changes and reindexing accordingly.
 
-#### Storage Indexes
+## Storage Indexes
 
 Many storage supports indexes, to boost efficiency in retrieving data.
 CocoIndex provides a common way to configure indexes for various storages.
 
-*   *Primary key*. `primary_key_fields` (`Sequence[str]`): the fields to be used as primary key. Types of the fields must be supported as key fields. See [Key Types](data_types#key-types) for more details.
-*   *Vector index*. `vector_indexes` (`Sequence[VectorIndexDef]`): the fields to create vector index. `VectorIndexDef` has the following fields:
+### Primary Key
+
+*Primary key* is specified by `primary_key_fields` (`Sequence[str]`).
+Types of the fields must be key types. See [Key Types](data_types#key-types) for more details.
+
+### Vector Index
+
+*Vector index* is specified by `vector_indexes` (`Sequence[VectorIndexDef]`). `VectorIndexDef` has the following fields:
+
     *   `field_name`: the field to create vector index.
-    *   `metric`: the similarity metric to use. See [Vector Type](data_types#vector-type) for more details about supported similarity metrics.
+    *   `metric`: the similarity metric to use.
+
+#### Similarity Metrics
+
+Following metrics are supported:
 
+| Metric Name | Description | Similarity Order |
+|-------------|-------------|------------------|
+| CosineSimilarity | [Cosine similarity](https://en.wikipedia.org/wiki/Cosine_similarity) | Larger is more similar |
+| L2Distance | [L2 distance (a.k.a. Euclidean distance)](https://en.wikipedia.org/wiki/Euclidean_distance) | Smaller is more similar |
+| InnerProduct | [Inner product](https://en.wikipedia.org/wiki/Inner_product_space) | Larger is more similar |
 
 ## Miscellaneous