Skip to content

Commit 306c45e

Browse files
authored
docs: clarify data type bindings rules for *Struct* types (#745)
1 parent 1fde241 commit 306c45e

File tree

1 file changed

+14
-7
lines changed

1 file changed

+14
-7
lines changed

docs/docs/core/data_types.mdx

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -21,10 +21,14 @@ All you need to do is to make sure the data passed to functions and targets are
2121
Each type in CocoIndex type system is mapped to one or multiple types in Python.
2222
When you define a [custom function](/docs/core/custom_function), you need to annotate the data types of arguments and return values.
2323

24-
* For return values, type annotation is required. Because this provides the ground truth to define the type of the output of the custom function.
25-
* For arguments, type annotation is only used to enable the conversion from data values already existing in CocoIndex engine to Python value.
26-
Type annotation is optional for basic types. When not specified, CocoIndex will use the *default Python type* for the argument.
27-
Type annotation is required for arguments of struct types and table types.
24+
* When you pass a Python value to the engine (e.g. return values of a custom function), type annotation is required,
25+
as it provides the ground truth of the data type in the flow.
26+
27+
* When you use a Python variable to bind to an engine value (e.g. arguments of a custom function),
28+
we use the type annotation as a guidance to construct the Python value.
29+
Type annotation is optional for basic types and struct types, and required for table types.
30+
31+
* When you define a [custom function](/docs/core/custom_function), type annotation is required for arguments and return values.
2832

2933
### Basic Types
3034

@@ -52,7 +56,7 @@ This is the list of all primitive types supported by CocoIndex:
5256
Notes:
5357

5458
* For some CocoIndex types, we support multiple Python types. You can annotate with any of these Python types.
55-
The first one is the *default Python type*, which means CocoIndex will create a value with this type when you don't annotate the type in function arguments.
59+
The first one is the default type, i.e. CocoIndex will create a value with this type when the type annotation is not provided (e.g. for arguments of a custom function).
5660

5761
* All Python types starting with `cocoindex.` are type aliases exported by CocoIndex. They're annotated types based on certain Python types:
5862

@@ -66,8 +70,8 @@ Notes:
6670
These aliases provide a non-ambiguous way to represent a specific type in CocoIndex, given their base Python types can represent a superset of possible values.
6771

6872
* When we say a CocoIndex type is *convertible to* another type, it means Python types for the second type can be also used to bind to a value of the first type.
69-
For example, *Float32* is convertible to *Float64*, so you can bind a value of *Float32* to a Python value of `float` or `np.float64` types.
70-
For *LocalDatetime*, when you use `cocoindex.OffsetDateTime` or `datetime.datetime` as the annotation to bind its value, the timezone will be set to UTC.
73+
* For example, *Float32* is convertible to *Float64*, so you can bind a value of *Float32* to a Python value of `float` or `np.float64` types.
74+
* For *LocalDatetime*, when you use `cocoindex.OffsetDateTime` or `datetime.datetime` as the annotation to bind its value, the timezone will be set to UTC.
7175

7276

7377
#### Json Type
@@ -133,6 +137,9 @@ class PersonTuple(NamedTuple):
133137
Both `Person` and `PersonTuple` are valid Struct types in CocoIndex, with identical schemas (three fields: `first_name` (Str), `last_name` (Str), `dob` (Date)).
134138
Choose `dataclass` for mutable objects or when you need additional methods, and `NamedTuple` for immutable, lightweight structures.
135139

140+
Besides, for arguments of custom functions, CocoIndex also supports using dictionaries (`dict[str, Any]`) to represent a *Struct* type.
141+
It's the default Python type if you don't annotate the function argument.
142+
136143
### Table Types
137144

138145
A *Table* type models a collection of rows, each with multiple columns.

0 commit comments

Comments
 (0)