logseq-schema

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Logseq Schema

Logseq 模式

Overview

概述

Use this skill to ground Datascript queries in Logseq's schema: core block/page/file attributes, built-in properties, built-in classes, and schema entities with :db/ident. Load

references/logseq-datascript-schema.md

for authoritative sources and query patterns, and

references/logseq-datascript-query-examples.md

for scenario-based query examples.

使用此技能可让Datascript查询基于Logseq的模式：核心块/页面/文件属性、内置属性、内置类，以及带有:db/ident的模式实体。加载

references/logseq-datascript-schema.md

获取权威来源和查询模式，加载

references/logseq-datascript-query-examples.md

获取基于场景的查询示例。

Glossary

术语表

```
db/id
```
: Internal numeric entity id (use with CLI flags like
```
--id
```
).
```
:block/uuid
```
: Stable UUID for a block entity; prefer when you need a persistent reference.
```
:block/name
```
: Lowercased page name, used for page lookup and joins.
```
:block/title
```
: Block or page title stored in the DB graph (use in queries when content text is needed).
```
:block/tags
```
: Ref-many attribute linking blocks to tag/page entities.
```
:user.property/<name>
```
: Namespace for user-defined properties stored directly on block entities.
```
:logseq.property/*
```
: Namespace for built-in properties stored directly on block entities.

```
db/id
```
: 内部数字实体ID（配合
```
--id
```
等CLI标志使用）。
```
:block/uuid
```
: 块实体的稳定UUID；当需要持久化引用时优先使用。
```
:block/name
```
: 小写的页面名称，用于页面查找和关联。
```
:block/title
```
: 存储在数据库图谱中的块或页面标题（当需要内容文本时在查询中使用）。
```
:block/tags
```
: 多引用属性，用于关联块与标签/页面实体。
```
:user.property/<name>
```
: 直接存储在块实体上的用户自定义属性命名空间。
```
:logseq.property/*
```
: 直接存储在块实体上的内置属性命名空间。

Important Notes

重要说明

Never use following block attrs in

query

pull

, these attrs are file-graph only, never used in db-graphs:

:block/format

:block/level

:block/level-spaces

:block/pre-block?

:block/properties-order

:block/properties-text-values

:block/invalid-properties

:block/macros

:block/file

:block.temp/ast-body

:block.temp/ast-blocks

:block/marker

:block/content

:block/priority

:block/scheduled

:block/deadline

:block/properties

:block/left

User properties are stored as
```
:user.property/<name>
```
attributes on the block/page entity.
Pull selectors do NOT support namespace wildcards like
```
:user.property/*
```
or
```
:logseq.property/*
```
. Only
```
*
```
(all attributes) or explicit attributes are allowed in
```
pull
```
.
To fetch user properties, either:
- Query datoms and filter attributes by namespace (e.g.,
```
user.property
```
  ), then merge into the entity map, or
- Discover explicit user property idents (via
```
:db/ident
```
  ) and include them explicitly in the pull selector.
Property values are often entities/refs (not always scalars). When rendering values, check for
```
:block/title
```
,
```
:block/name
```
, or
```
:logseq.property/value
```
on the value entity before falling back to stringifying.
Many properties are
```
:db.cardinality/many
```
(values may be sets/vectors). Treat them as collections in queries and formatting.

切勿在

query

或

pull

中使用以下块属性，这些属性仅属于文件图谱，从不用于数据库图谱：

:block/format

:block/level

:block/level-spaces

:block/pre-block?

:block/properties-order

:block/properties-text-values

:block/invalid-properties

:block/macros

:block/file

:block.temp/ast-body

:block.temp/ast-blocks

:block/marker

:block/content

:block/priority

:block/scheduled

:block/deadline

:block/properties

:block/left

。

用户属性以
```
:user.property/<name>
```
属性的形式存储在块/页面实体上。
拉取选择器不支持命名空间通配符，如
```
:user.property/*
```
或
```
:logseq.property/*
```
。在
```
pull
```
中仅允许使用
```
*
```
（所有属性）或明确的属性。
要获取用户属性，可选择以下两种方式：
- 查询数据原子并按命名空间过滤属性（例如
```
user.property
```
  ），然后合并到实体映射中；
- 发现明确的用户属性标识符（通过
```
:db/ident
```
  ）并将其明确包含在拉取选择器中。
属性值通常是实体/引用（并非总是标量）。渲染值时，先检查值实体上的
```
:block/title
```
、
```
:block/name
```
或
```
:logseq.property/value
```
，再回退到字符串化处理。
许多属性是
```
:db.cardinality/many
```
（值可能是集合/向量）。在查询和格式化时将其视为集合处理。

Datascript Query Mistakes To Avoid

需避免的Datascript查询错误

In
```
query
```
```
:where
```
/
```
pull
```
/
```
find
```
, attributes cannot use namespace wildcards (e.g.,
```
:logseq.property/*
```
,
```
:user.property/*
```
); you must use full attr
```
:db/ident
```
values (e.g.,
```
:logseq.property/status
```
,
```
:user.property/background
```
). In
```
pull
```
, only
```
*
```
(all attributes) is special.
Avoid nesting function calls inside predicates in
```
:where
```
(some Datascript engines reject or mis-handle it). Bind the function result first, then compare.

Example of safe namespace filtering:

clojure

[:find [?a ...]
 :where
 [?e :db/ident ?a]
 [(namespace ?a) ?ns]
 [(= ?ns "user.property")]]

在
```
query
```
的
```
:where
```
/
```
pull
```
/
```
find
```
中，属性不能使用命名空间通配符（例如
```
:logseq.property/*
```
、
```
:user.property/*
```
）；必须使用完整的属性
```
:db/ident
```
值（例如
```
:logseq.property/status
```
、
```
:user.property/background
```
）。在
```
pull
```
中，只有
```
*
```
（所有属性）是特殊用法。
避免在
```
:where
```
的谓词中嵌套函数调用（部分Datascript引擎会拒绝或错误处理）。先绑定函数结果，再进行比较。

安全的命名空间过滤示例：

clojure

[:find [?a ...]
 :where
 [?e :db/ident ?a]
 [(namespace ?a) ?ns]
 [(= ?ns "user.property")]]

Workflow

工作流程

1) Locate schema facts

1) 查找模式信息

Open
```
references/logseq-datascript-schema.md
```
.
Review the core attribute list and helper sets for ref/cardinality details.
Review built-in properties and classes to understand available attributes and required fields.

打开
```
references/logseq-datascript-schema.md
```
。
查看核心属性列表和辅助集合，了解引用/基数的详细信息。
查看内置属性和类，了解可用属性和必填字段。

2) Write or validate queries

2) 编写或验证查询

Prefer
```
:block/*
```
attributes for block/page queries; use properties/classes only when needed.
If unsure about available
```
:db/ident
```
entities, run the CLI query listed in the references file.
For user properties, query against
```
:user.property/<name>
```
directly; for built-ins, use
```
:logseq.property/<name>
```
.

在块/页面查询中优先使用
```
:block/*
```
属性；仅在需要时使用属性/类。
如果不确定可用的
```
:db/ident
```
实体，运行参考文件中列出的CLI查询。
对于用户属性，直接查询
```
:user.property/<name>
```
；对于内置属性，使用
```
:logseq.property/<name>
```
。

3) Keep queries consistent with schema

3) 保持查询与模式一致

Respect ref vs scalar attributes and
```
:db.cardinality/many
```
when joining.
Use property/class definitions to confirm public/queryable status before exposing a query to users.

关联时要区分引用属性和标量属性，以及
```
:db.cardinality/many
```
。
在向用户公开查询之前，使用属性/类定义确认其公开/可查询状态。

Resources

资源

references/

```
logseq-datascript-schema.md
```
```
logseq-datascript-query-examples.md
```

```
logseq-datascript-schema.md
```
```
logseq-datascript-query-examples.md
```

Quick Examples

快速示例

Pull user properties for a block

拉取块的用户属性

clojure

;; Discover idents, then pull explicitly.
[:db/id :block/title :user.property/background :user.property/notes]

clojure

;; 发现标识符，然后明确拉取。
[:db/id :block/title :user.property/background :user.property/notes]

Query blocks with a user property

查询带有用户属性的块

clojure

[:find ?b ?v
 :where
 [?b :user.property/background ?v]]

clojure

[:find ?b ?v
 :where
 [?b :user.property/background ?v]]

Render a property value

渲染属性值

Order of preference when value is a map/entity:

```
:block/title
```
```
:block/name
```
```
:logseq.property/value
```

当值为映射/实体时，优先顺序：

```
:block/title
```
```
:block/name
```
```
:logseq.property/value
```