0x3 Snapshots

A snapshot here refers to the data structure describing a datasheet. The front-end builds the user interface by parsing this data structure, and the back-end maintains this data structure to implement functional logic.

Let's take a look at a real data structure:


A snapshot is returned in the dataPack interface. In addition to the datasheetId describing which datasheet it belongs to, meta and recordMap store important information about the table structure and table data. Let's unfold and describe them.

Meta

As the name suggests, metadata does not actually contain the data entities of table records, but it plays a very important role. You can think of meta as defining the schema of the data structure.

FieldMap

FieldMap defines the schema of the entire table data structure. It is a K-V structure with key as fieldId and value as field attributes. FieldMap does not store order information; it is a collection of the whole table structure. To see these fields on the table, we need to combine column information, which will be discussed in the views section below.

Field

APITable currently has 24 field types, including 15 basic fields and 9 advanced fields. The specific definitions can be found in datasheet/packages/core/src/model. The definition of basic fields is: users can edit directly, and each field has its own type of interactive editor to help users more easily enter data of that type and limit the entry of non-compliant data. Advanced fields usually have special functions. In code implementation, except for magic links, all other fields in advanced fields are "computed fields" because their values are not static but dynamically generated through some specific conditions. Therefore, we cannot edit cells of these field types directly.

  • Magic Link: The only field in advanced fields that allows users to edit the values in the record. Users can select the linked table to select corresponding records through the link selector, just like joining them together in a database through primary keys. The linked records will be displayed in the cell with their first column (PrimaryField) value.

  • Rollup: Based on the magic link relationship between tables and records, cross-table data referencing and summary calculation is performed.

  • Formula:




PrimaryField

APITable's first column is a bit different. To ensure the relative uniqueness of the content, fewer data types are supported in the data structure, and fields that tend to maintain duplicate data are removed. The first column cannot be dragged, and the "magic link" cannot be the first column.


Since it cannot be dragged, it is always the first column. In practice, the primaryField has no essential difference from other fields except for the added restrictions. It does not act as a "primary key" in the database. To distinguish between columns and fields, we usually call it column order/column hiding when discussing order/shown or hiding. When discussing structure, attributes, and types, we call it field type.

Views

Views is an array of view information data. Unlike fieldMap, the order of the views array determines the order of the view tabs themselves. Let's take a look at the simplest views data:

[
    {
        "id": "viwUbzkXrV0YK",
        "name": "APITable view",
        "autoSave": false,
        "frozenColumnCount": 1,
        "type": 1,
        "rows": [
            {"recordId": "recVopLz0C6EV"},
            {"recordId": "recLHrg2MmByK"},
        ],
        "columns": [
            {"fieldId": "fldjQo71Wn32G", "statType": 1},
            {"fieldId": "fldKoJx7ViqqQ"},
        ],
    },
]

The outermost array contains an object that stores the view data named "APITable View". The first five properties are:

  • id: view id (note that the view id is unique only within the current table and may be duplicated in other tables when copying tables)

  • name: view name

  • autoSave: whether to automatically save

  • type: view type (table, kanban, gallery...)

  • rows: row order and properties, associated with recordMap through recordId

  • columns: column order and properties, associated with fieldMap through fieldId

These data structures make up the simplest form of view you see, the view display style, and row and column order. However, they do not include the record data itself, and we will discuss the design of views in the next chapter.

RecordMap

RecordMap is a key-value pair with recordId as key and record data as value. First, it is unordered, and the order of records is determined by the rows in the view. RecordMap contains all the record data in the table, and its keys match the IDs in rows one by one.

{
    "recl1X8h2qQ4J": {
        "id": "recl1X8h2qQ4J",
        "data": {
            "fldO3L8OlyzNC": [{"type": 1, "text": "1"}],
            "fldzySdRslVdV": ["optRUvCnsB9pM"]
        },
        "stringify": {
            "fldO3L8OlyzNC": "1",
            "fldzySdRslVdV": "2"
        },
        "createdAt": 1655876993000,
        "updatedAt": 1655973169721,
        "revisionHistory": [0,3,7,15,16,17],
        "recordMeta": {
            "createdAt": "2022-06-22T05:49:53.883Z",
            "createdBy": "eeb620a54e2248c69c25de68e6eb668c",
            "fieldUpdatedMap": {
                "fldO3L8OlyzNC": {
                    "by": "9166bea35d79456994b99956dbfabcb9",
                    "at": 1655973162989
                },
                "fldzySdRslVdV": {
                    "by": "9166bea35d79456994b99956dbfabcb9",
                    "at": 1655973169155
                }
            }
        },
        "commentCount": 0
    }
}

Let's take a look at what the first layer of kv in the record data represents without further ado:

  • id: the value of recordId (note that recordId is unique only within the current table and may be duplicated in other tables when copying tables), which matches the id in rows one by one

  • data: the cellvalue data of the table, which stores the original data structure of cellvalue. Each field has its unique data structure. The cellvalue of basic fields comes from user input, while the cellvalue of computed fields comes from calculation results. How cellvalue values are displayed often requires a comprehensive judgment in conjunction with the field settings.

  • revisionHistory: an array of version numbers. When a modified version of the table is related to this record, the version number will be recorded here, which will be discussed in detail in 0x8 version control Version Control.

  • recordMeta: maintains the current record's modifier, creator, modification time, creation time, and is accurate to the field level (already removed from the snapshot in TeamX environment)

  • commentCount: number of comments

Among the above content, the most important data are data and stringify, which save the entity of the record data. The subsequent table function implementation and calculation operations are all carried out on them.