Skip to content

Commit 513c978

Browse files
committed
docs: add corresponding instructions for using NamedTuple to define a struct
1 parent 2fd41c1 commit 513c978

File tree

1 file changed

+31
-9
lines changed

1 file changed

+31
-9
lines changed

docs/docs/core/data_types.mdx

Lines changed: 31 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -53,23 +53,41 @@ The native Python type is always more permissive and can represent a superset of
5353
you can choose whatever to use.
5454
The native Python type is usually simpler.
5555

56-
### Struct Type
56+
### Struct Types
5757

5858
A Struct has a bunch of fields, each with a name and a type.
5959

60-
In Python, a Struct type is represented by a [dataclass](https://docs.python.org/3/library/dataclasses.html),
61-
and all fields must be annotated with a specific type. For example:
60+
In Python, a Struct type is represented by either a [dataclass](https://docs.python.org/3/library/dataclasses.html)
61+
or a [NamedTuple](https://docs.python.org/3/library/typing.html#typing.NamedTuple), with all fields annotated with a specific type.
62+
Both options define a structured type with named fields, but they differ slightly:
63+
64+
- **Dataclass**: A flexible class-based structure, mutable by default, defined using the `@dataclass` decorator.
65+
- **NamedTuple**: An immutable tuple-based structure, defined using `typing.NamedTuple`.
66+
67+
For example:
6268

6369
```python
6470
from dataclasses import dataclass
71+
from typing import NamedTuple
72+
import datetime
6573

74+
# Using dataclass
6675
@dataclass
6776
class Person:
6877
first_name: str
69-
last_name
78+
last_name: str
79+
dob: datetime.date
80+
81+
# Using NamedTuple
82+
class PersonTuple(NamedTuple):
83+
first_name: str
84+
last_name: str
7085
dob: datetime.date
7186
```
7287

88+
Both `Person` and `PersonTuple` are valid Struct types in CocoIndex, with identical schemas (three fields: `first_name` (Str), `last_name` (Str), `dob` (Date)).
89+
Choose `dataclass` for mutable objects or when you need additional methods, and `NamedTuple` for immutable, lightweight structures.
90+
7391
### Table Types
7492

7593
A Table type models a collection of rows, each with multiple columns.
@@ -84,20 +102,24 @@ The row order of a KTable is not preserved.
84102
Type of the first column (key column) must be a [key type](#key-types).
85103

86104
In Python, a KTable type is represented by `dict[K, V]`.
87-
The `V` should be a dataclass, representing the value fields of each row.
88-
For example, you can use `dict[str, Person]` to represent a KTable, with 4 columns: key (Str), `first_name` (Str), `last_name` (Str), `dob` (Date).
105+
The `V` should be a struct type, either a `dataclass` or `NamedTuple`, representing the value fields of each row.
106+
For example, you can use `dict[str, Person]` or `dict[str, PersonTuple]` to represent a KTable, with 4 columns: key (Str), `first_name` (Str), `last_name` (Str), `dob` (Date).
89107

90-
Note that if you want to use a struct as the key, you need to annotate the struct with `@dataclass(frozen=True)`, so the values are immutable.
108+
Note that if you want to use a struct as the key, you need to annotate the struct with `@dataclass(frozen=True)`, For `NamedTuple`, immutability is built-in. so the values are immutable.
91109
For example:
92110

93111
```python
94112
@dataclass(frozen=True)
95113
class PersonKey:
96114
id_kind: str
97115
id: str
116+
117+
class PersonKeyTuple(NamedTuple):
118+
id_kind: str
119+
id: str
98120
```
99121

100-
Then you can use `dict[PersonKey, Person]` to represent a KTable keyed by `PersonKey`.
122+
Then you can use `dict[PersonKey, Person]` or `dict[PersonKeyTuple, PersonTuple]` to represent a KTable keyed by `PersonKey` or `PersonKeyTuple`.
101123

102124

103125
#### LTable
@@ -118,4 +140,4 @@ Currently, the following types are key types
118140
- Range
119141
- Uuid
120142
- Date
121-
- Struct with all fields being key types
143+
- Struct with all fields being key types (using `@dataclass(frozen=True)` or `NamedTuple`)

0 commit comments

Comments
 (0)