seed-data

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Steedos Seed Data | Steedos 初始化数据

Steedos 初始化数据

Overview | 概述

概述

Seed data files provide initial records that are automatically imported when the service starts or a workspace initializes. They are placed in

main/default/data/

and support JSON, YAML, and CSV formats.

初始化数据文件提供服务启动或工作区初始化时自动导入的初始记录，放在

main/default/data/

目录下，支持 JSON、YAML、CSV 格式。

种子数据文件提供服务启动或工作区初始化时自动导入的初始记录，存放于

main/default/data/

目录下，支持JSON、YAML和CSV格式。

File Location | 文件位置

文件位置

steedos-packages/
└── my-package/
    └── main/default/
        └── data/
            ├── products.data.json
            ├── categories.data.yml
            └── regions.data.csv

steedos-packages/
└── my-package/
    └── main/default/
        └── data/
            ├── products.data.json
            ├── categories.data.yml
            └── regions.data.csv

Naming Convention | 命名规则

命名规则

{objectName}.data.json
{objectName}.data.yml
{objectName}.data.csv

The file name before the first

is the object API name (i.e. the MongoDB collection name).

文件名第一个

之前的部分是对象 API 名称（即 MongoDB collection 名称）。

{objectName}.data.json
{objectName}.data.yml
{objectName}.data.csv

文件名中第一个

之前的部分是对象API名称（即MongoDB集合名称）。

File Structure | 文件结构

文件结构

JSON Format | JSON 格式

JSON格式

json

[
  {
    "_id": "product_001",
    "name": "标准服务套餐",
    "price": 9800,
    "status": "active"
  },
  {
    "_id": "product_002",
    "name": "高级服务套餐",
    "price": 19800,
    "status": "active"
  }
]

json

[
  {
    "_id": "product_001",
    "name": "标准服务套餐",
    "price": 9800,
    "status": "active"
  },
  {
    "_id": "product_002",
    "name": "高级服务套餐",
    "price": 19800,
    "status": "active"
  }
]

YAML Format | YAML 格式

YAML格式

yaml

- _id: "product_001"
  name: "标准服务套餐"
  price: 9800
  status: "active"

- _id: "product_002"
  name: "高级服务套餐"
  price: 19800
  status: "active"

yaml

- _id: "product_001"
  name: "标准服务套餐"
  price: 9800
  status: "active"

- _id: "product_002"
  name: "高级服务套餐"
  price: 19800
  status: "active"

CSV Format | CSV 格式

CSV格式

csv

_id,name,price,status
product_001,标准服务套餐,9800,active
product_002,高级服务套餐,19800,active

csv

_id,name,price,status
product_001,标准服务套餐,9800,active
product_002,高级服务套餐,19800,active

Required Fields | 必填字段

必填字段

Field	Description
`_id`	Unique record identifier. Required for every record.

The following fields are auto-populated on import (do NOT include them manually):

Auto Field	Description
`space`	Workspace ID
`owner`	Workspace owner
`created`	Creation timestamp
`created_by`	Creator
`modified`	Modification timestamp
`modified_by`	Modifier
`company_id`	Company ID
`company_ids`	Company IDs

字段	描述
`_id`	唯一记录标识符。每条记录都必须填写。

以下字段在导入时会自动填充（请勿手动添加）：

自动填充字段	描述
`space`	工作区ID
`owner`	工作区所有者
`created`	创建时间戳
`created_by`	创建者
`modified`	修改时间戳
`modified_by`	修改者
`company_id`	公司ID
`company_ids`	公司ID列表

Template Variables | 模板变量

模板变量

Use template variables for workspace-dependent IDs:

Variable	Replaced With
`${space_id}`	Current workspace ID
`${space_owner_id}`	Workspace owner user ID

yaml

- _id: "${space_id}_default_config"
  name: "default_config"
  space: "${space_id}"
  owner: "${space_owner_id}"
  setting_key: "theme"
  setting_value: "blue"

使用模板变量来适配工作区相关的ID：

变量	替换值
`${space_id}`	当前工作区ID
`${space_owner_id}`	工作区所有者用户ID

yaml

- _id: "${space_id}_default_config"
  name: "default_config"
  space: "${space_id}"
  owner: "${space_owner_id}"
  setting_key: "theme"
  setting_value: "blue"

Date Format | 日期格式

日期格式

Use EJSON

$date

format for date/datetime fields:

json

[
  {
    "_id": "record_001",
    "name": "示例记录",
    "start_date": { "$date": "2024-01-01T00:00:00.000Z" },
    "created": { "$date": "2024-01-01T08:00:00.000Z" }
  }
]

日期/时间字段请使用EJSON的

$date

格式：

json

[
  {
    "_id": "record_001",
    "name": "示例记录",
    "start_date": { "$date": "2024-01-01T00:00:00.000Z" },
    "created": { "$date": "2024-01-01T08:00:00.000Z" }
  }
]

Import Behavior | 导入行为

导入行为

Seed data is imported at two points:

Trigger	Mode	Behavior
Service startup	`onlyInsert`	Only imports if records do NOT already exist. If any record by `_id` is found, the entire import is skipped.
Space initialized	`upsert`	Inserts new records, updates existing records (matched by `_id` ).

On upsert, existing records preserve their original

space

owner

created

created_by

values; only

modified

and

modified_by

are updated.

种子数据会在两个时机被导入：

触发时机	模式	行为
服务启动	`onlyInsert`	仅当记录不存在时导入。若通过 `_id` 发现任何已存在的记录，则跳过整个导入流程。
工作区初始化	`upsert`	插入新记录，更新已存在的记录（通过 `_id` 匹配）。

在upsert模式下，已存在的记录会保留原有的

space

、

owner

、

created

、

created_by

值；仅更新

modified

和

modified_by

字段。

Complete Example | 完整示例

完整示例

steedos-packages/
└── my-package/
    └── main/default/
        ├── objects/
        │   └── products/
        │       ├── products.object.yml
        │       └── fields/
        │           └── ...
        └── data/
            └── products.data.yml

yaml

undefined

steedos-packages/
└── my-package/
    └── main/default/
        ├── objects/
        │   └── products/
        │       ├── products.object.yml
        │       └── fields/
        │           └── ...
        └── data/
            └── products.data.yml

yaml

undefined

main/default/data/products.data.yml

_id: "${space_id}_prod_basic" name: "基础版" code: "BASIC" price: 9800 is_active: true
_id: "${space_id}_prod_pro" name: "专业版" code: "PRO" price: 29800 is_active: true
_id: "${space_id}_prod_enterprise" name: "企业版" code: "ENTERPRISE" price: 99800 is_active: true

undefined

_id: "${space_id}_prod_basic" name: "基础版" code: "BASIC" price: 9800 is_active: true
_id: "${space_id}_prod_pro" name: "专业版" code: "PRO" price: 29800 is_active: true
_id: "${space_id}_prod_enterprise" name: "企业版" code: "ENTERPRISE" price: 99800 is_active: true

undefined

Best Practices | 最佳实践

最佳实践

Always include
_id
: Every record must have a unique
```
_id
```
. Use
```
${space_id}
```
prefix for workspace-scoped data.
Use YAML for readability: YAML is easier to maintain than JSON for seed data.
Don't set auto fields: Do not include
```
space
```
,
```
owner
```
,
```
created
```
,
```
created_by
```
,
```
modified
```
,
```
modified_by
```
— they are auto-populated.
Idempotent IDs: Use deterministic
```
_id
```
values (not random) so repeated imports don't create duplicates.
Match object API name: The filename must exactly match the object's API name (e.g.,
```
orders.data.yml
```
for the
```
orders
```
object).
Keep data minimal: Only include essential initial data (config, default options, system records). Don't use for large datasets.

始终包含
_id
：每条记录必须拥有唯一的
```
_id
```
。对于工作区范围的数据，使用
```
${space_id}
```
作为前缀。
使用YAML提升可读性：相较于JSON，YAML更易于维护种子数据。
不要设置自动填充字段：请勿手动添加
```
space
```
、
```
owner
```
、
```
created
```
、
```
created_by
```
、
```
modified
```
、
```
modified_by
```
字段——这些字段会自动填充。
使用幂等ID：使用确定的
```
_id
```
值（而非随机值），避免重复导入时创建重复记录。
匹配对象API名称：文件名必须与对象的API名称完全匹配（例如，
```
orders
```
对象对应
```
orders.data.yml
```
）。
保持数据精简：仅包含必要的初始数据（配置、默认选项、系统记录）。请勿用于大型数据集。