logseq-schema

Logseq Schema

概要

このスキルを使って、Logseq のスキーマに基づいた Datascript クエリを作成します。対象となるのは、ブロック、ページ、ファイルのコア属性、組み込みプロパティ、組み込みクラス、および :db/ident を持つスキーマエンティティです。信頼できる情報源とクエリパターンについては references/logseq-datascript-schema.md を、シナリオ別のクエリ例については references/logseq-datascript-query-examples.md を読み込んでください。

用語集

• db/id：内部の数値エンティティ ID です（--id などの CLI フラグで使用します）。
• :block/uuid：ブロックエンティティの安定した UUID です。永続的な参照が必要な場合に優先して使用してください。
• :block/name：小文字に変換されたページ名で、ページの検索や結合に使用します。
• :block/title：DB グラフに保存されたブロックまたはページのタイトルです（コンテンツテキストが必要なクエリで使用します）。
• :block/tags：ブロックをタグ／ページエンティティにリンクする ref-many 属性です。
• :user.property/<name>：ブロックエンティティに直接保存される、ユーザー定義プロパティの名前空間です。
• :logseq.property/*：ブロックエンティティに直接保存される、組み込みプロパティの名前空間です。

重要な注意事項

• 次のブロック属性は query または pull で使用しないでください。これらはファイルグラフ専用であり、DB グラフでは使用されません。 :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> 属性として保存されます。
• Pull セレクターでは、:user.property/* や :logseq.property/* などの名前空間ワイルドカードはサポートされません。 pull で使用できるのは *（すべての属性）または明示的な属性のみです。
• ユーザープロパティを取得するには、次のいずれかを行います。
  • データムをクエリし、名前空間（例：user.property）で属性をフィルタリングしてから、エンティティマップに統合する
  • 明示的なユーザープロパティの ident（:db/ident 経由）を特定し、pull セレクターに明示的に含める
• プロパティ値は、多くの場合エンティティ／ref です（常にスカラーとは限りません）。値を表示するときは、文字列化する前に値のエンティティに :block/title、:block/name、または :logseq.property/value があるか確認してください。
• 多くのプロパティは :db.cardinality/many です（値はセット／ベクターになることがあります）。クエリや整形ではコレクションとして扱ってください。

避けるべき Datascript クエリの誤り

• query の :where／pull／find では、属性に名前空間ワイルドカード（例：:logseq.property/*、:user.property/*）を使用できません。完全な attr :db/ident 値（例：:logseq.property/status、:user.property/background）を使用する必要があります。pull では *（すべての属性）のみが特殊な値です。
• :where の述語内に関数呼び出しをネストしないでください（Datascript エンジンによっては拒否されたり、誤って処理されたりします）。関数の結果を先に束縛してから比較してください。

名前空間を安全にフィルタリングする例：

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

ワークフロー

1) スキーマの情報を確認する

• references/logseq-datascript-schema.md を開きます。
• ref／カーディナリティの詳細について、コア属性の一覧とヘルパーセットを確認します。
• 使用可能な属性と必須フィールドを把握するため、組み込みプロパティとクラスを確認します。

2) クエリを作成または検証する

• ブロック／ページのクエリでは :block/* 属性を優先し、必要な場合にのみプロパティ／クラスを使用します。
• 使用可能な :db/ident エンティティがわからない場合は、参照ファイルに記載された CLI クエリを実行します。
• ユーザープロパティには :user.property/<name> を直接、組み込みプロパティには :logseq.property/<name> を使用してクエリします。

3) クエリをスキーマに沿わせる

• 結合する際は、ref 属性とスカラー属性の違い、および :db.cardinality/many を考慮します。
• クエリをユーザーに公開する前に、プロパティ／クラスの定義で公開／クエリ可能な状態か確認します。

リソース

references/

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

簡単な例

ブロックのユーザープロパティを取得する

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

ユーザープロパティを持つブロックをクエリする

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

プロパティ値をレンダリングする

値がマップ／エンティティの場合の優先順位：

1. :block/title
2. :block/name
3. :logseq.property/value