Field property
Overview
| Option | Type | Description |
|---|---|---|
unique | bool | Check field uniqueness. Default: false. Specially for map (or KeyedList) key, default will be auto deduced. |
range | string | Format: "left, right". E.g.: "1,10", "1,~", "~,10".Different interpretations of range: - number: value range. - string: count of utf-8 code point. |
refer | string | Format: "SheetName(SheetAlias).ColumnName".Ensure this field is in another sheet’s column value space. Multiple refers are comma-separated. |
sequence | int64 | Ensure this field’s value is a sequence and begins with this value. |
default | string | Use this default value if cell is empty. |
fixed | bool | Auto-detected fixed size of horizontal list/map. Default: false. |
size | uint32 | Specify fixed size of horizontal list/map. |
form | Form | Specify cell data form of incell struct. - FORM_TEXT- FORM_JSON |
json_name | string | Specify field’s custom JSON name instead of lowerCamelCase name of proto field name. |
present | bool | Must fill cell data explicitly if present is true. Default: false. |
optional | bool | Whether this field is optional (field name existence). |
patch | Patch | Field patch type. - PATCH_REPLACE- PATCH_MERGE |
sep | string | Field-level separator. |
subsep | string | Field-level subseparator. |
cross | int32 | Specify count of crossed nodes/cells/fields of composite types with cardinality, such as list and map. |
Option unique
Option unique can be specified as true or false in the field property.
- If you set
uniquetotrueexplicitly, then tableau will report an error if a duplicate key is appeared. - If you set
uniquetofalseexplicitly, no check will be performed.
Map (or KeyedList) key
Tableau will auto deduce the map (or KeyedList) key’s unique as true or not.
The rule is: if a map’s value type (or KeyedList element type) has no sub map/list field of the same layout (vertical/horizontal), then the key must be unique.
So in most cases, it’s not neccessary to config it explicitly.
General scalar field
If you specify a general scalar field’s property unique as true, then tableau will check the field’s uniquness in map or list.
Option range
Option range can be specified as format: "left, right" (left and right are both inclusive).
Different interpretations of range:
- number: value range, e.g.:
"1,10","1,~","~,10". - string: count of utf-8 code point.
- list: length of list.
- map: length of map.
Option refer
Option refer is some like the FOREIGN KEY constraint in SQL to prevent actions that would destroy links between tables. However, tableau refer can refer to any sheet’s column even if it is not map key column, and multiple refers (comma-separated) are also supported. It is used to ensure this field is at least in one of the other sheets' column value space (aka message’s field value space).
Format: "SheetName(SheetAlias).ColumnName[,SheetName(SheetAlias).ColumnName]...".
For example:
map<uint32, Reward>|{refer:"ItemConf.ID"}: single-refer without alias, so sheet name is just the generated protobuf message name.map<uint32, Reward>|{refer:"ItemConf.ID,EquipConf.ID"}: multi-refer without alias, then sheet alias is the generated protobuf message name.map<uint32, Reward>|{refer:"Sheet1(ItemConf).ID"}: single-refer with alias, then sheet alias is the generated protobuf message name.
Option sequence
Option sequence is used to ensure this fieldโs value is a sequence and begins with this value,
and mainly used for map key and list element.
For example:
map<uint32, Item>|{sequence:1}: this map key must follow the sequence rule which begins with value1.
Option default
If option default is set, then use it as default value if cell is empty.
Option fixed
If option fixed is set as true, then auto-detect fixed size of horizontal list/map.
For example:
Option size
Option size is used to specify fixed size of horizontal list/map.
For example:
Option form
Option form is used to specify cell data form of incell struct.
Two kinds of form can be specified:
FORM_TEXT: protobuf text format.FORM_JSON: protobuf JSON format.
For detailed demos, see Advanced predefined incell struct โ.
Option json_name
By default, JSON name is deduced from the field’s proto name by converting it to camelCase. Now you
can explicitly specify it by json_name prop option.
For example, a worksheet ItemConf in HelloWorld.xlsx:
| ID | Rarity_1 | SpecialEffect_2 |
|---|---|---|
| map<int32, Item> | int32|{json_name:“rarity_1”} | int32|{json_name:“specialEffect_2”} |
| Item’s ID | Item’s rarity. | Item’s special effect. |
| 1 | 10 | 101 |
| 2 | 20 | 102 |
| 3 | 30 | 103 |
Option present
If option present is set as true, then cell data cannot be empty and must be filled explicitly.
Otherwise an error will be reported.
Option optional
Specify whether this field is optional (field name existence).
If set to true, then:
- table formats (Excel/CSV): field’s column can be absent.
- document formats (XML/YAML): field’s name can be absent.
Option patch
See field-level patch in Option Patch โ.
Option sep
Field-level separator for separating:
- incell list elements (scalar or struct).
- incell map items.
If not set, it will use sheet-level seq in metasheet.
Option subsep
Field-level subseparator for separating:
- key-value pair of each incell map item.
- struct fields of each incell struct list element.
If not set, it will use sheet-level subseq in metasheet.
Option cross
Specify count of crossed nodes/cells/fields of composite types with cardinality, such as list and map.
union list field
Specify the count of union fields the list will cross and occupy (one list element for each field). It will also change this list field’s layout from incell to horizontal.
- Value 0 means it is an incell list.
- Value > 0 means it is a horizontal list occupying N fields.
- Value < 0 means it is a horizontal list occupying all following fields.
TODO: example illustrated.