CQL の記述とデバッグ

CQL の記述とデバッグ は何をしますか？

CQL は Croct の英語ライクなクエリ言語です。同じ式の構文が、オーディエンス、SDK および HTTP API からのリアルタイム評価、動的コンテンツ値にわたって使用されます。ここに記載されている内容はすべて docs.croct.com からのものです。記載されていない内容がある場合は、推測せずにライブドキュメント（このファイルの下部）を確認してください。

ワークフロー

1. クエリが実行される場所を特定します：オーディエンス（ブール値である必要あり）、evaluate/API（任意の JSON 値、最大 500 文字）、または動的値（結果が属性タイプに適合する必要あり、そうでない場合は default）。
2. データソースを選択します：現在のコンテキスト（page、cart、location、campaign、device）、保存されたプロファイル（user's ...、user's stats）、セッション（session's ...）、または履歴（user has ... イベント式、Scale プラン）。
3. データが収集されていることを確認します：統合必須 とマークされたもの（プロファイル属性、カート、興味、目標、サインイン状態）は、アプリがそれを送信しない限り決してマッチしません。
4. 以下のチートシートを使用して記述します。正確なプロパティは context-and-data-types.md で確認してください。
5. 落とし穴チェックリストを実行し、croct.evaluate() またはダッシュボードの推定ツールでテストします。

チートシート

// 自然なスタイル、技術的なスタイル、混合スタイルはすべて交換可能です
user's score is greater than 90
user.score > 90
user's score > 90

ニーズ	構文
プロパティ	user's address's city、user's stats' orders、property city of user's address、user.address.city
特殊なキー / インデックス	page.query['coupon-code']、list[0]、(user's interests)[0]
セレクタ	cart.items[1st]、[:first]、[:last(2)]、items[*].price、data[...].price
リテラル	null、true、42、3.14（小数）、3.14f、51%、"str"、'raw'、~/re/i、[1, 2]、["k": "v"]
日付	リテラルなし："2026-01-01" as date、"2026-01-01T12:00" as datetime; today + 1 day
論理	and or not（&& `
比較	== != > >= < <=; 1 < x < 3; is equal to X ignoring case
リテラル短縮形	X is "value"、X is not 0（右辺はリテラルである必要があります）
文字列	starts with、ends with、matches "sub" / matches ~/re/i（大文字小文字区別）、is like "sub"（大文字小文字区別なし）
コレクション	contains X、X is in [..]、contains all of [..]、contains either [..]、contains neither [..]
存在	is defined / is known、is empty
ユーザー/セッション	user is returning、user is anonymous、user is identified、session is starting
日付	is before、is after、is at "12:00"、is between A and B [exclusive]、today's weekday is "monday"
定量子	some x in C satisfies P、every、no、not every、at least 2 of any [distinct] x in C satisfies P
マクロ	count of、sum of、average of、min of、max of、first of、last of、keys of、length of、number of days between A and B、this month
修飾子	as number、rounded [down]、in title case、sorted descending、without duplicates、replacing "a" with "b"、today at "12:00"
フォールバック	user's name or else "Anonymous"（??）
条件文	"A" if cond otherwise "B"、cond ? "A" : "B"
変数	let orders = user's stats' orders; orders >= 5
イベント（Scale）	user has <event> [with prop value] [at least N times] [in last 7 days]
コメント	// line、# line、/* block */

キーワードと識別子は大文字小文字を区別しませんが、文字列リテラルは大文字小文字を区別します。

コンテキスト概要

変数	共通プロパティ
user	id、firstName、email、age、company、jobTitle、interests、activities、stats' sessions、stats' orders、任意のカスタム属性
session	start、duration、landingPage、referrer、stats' pageviews、stats' orders、audiences、experiences、experiments、カスタム属性
page（Web）	title、url、path、query、anchor、referrer
location	continentCode、countryCode、countryName、stateCode/regionCode（state's code のエイリアス）、stateName、cityName、timeZone、tags
device / browser	category（desktop、tablet、mobile、bot...）、vendor、name、os; browser's name、type
campaign	name、source、medium、content、term（UTM）
cart	stage（browsing、shopping、checkout）、items、total、subtotal、coupon、discount
context	timeZone、評価時に渡される属性
now、today、yesterday、tomorrow	weekday、day、month、year、hour...

最も便利なパターン

user is returning
user is not returning
session is starting
device's category is "mobile"
device's category is not "bot"
location's countryCode is "US"
location's state's code is in ["NY", "CA"]
location's cityName is "New York" and today's weekday is "monday"
campaign's source is "google" and campaign's medium is "cpc"
campaign's name matches "sale"
page's path is in ["/pricing", "/plans"]
page's query's newsletter is "daily-news"
page.query['coupon-code'] is defined
session's referrer matches "google"
session's landingPage starts with "https://example.com/promo"
session's duration > 5 minutes and session's stats' orders is 0
user's interests contains either ["marketing", "sales"]
user's age is between 18 and 30
user's stats' orders is 0
user's plan is "premium"
cart's stage is "checkout" and cart's total is greater than 100
some item in cart's items satisfies item's brand is "Apple"
(no item in cart's items satisfies item's name is like "smartphone") and user is returning
user has abandoned a cart at least 2 times
user has viewed a product with category "Shoes" in last 7 days
user has completed goal "demo-requested" last session
user's firstName or else "there"

ユースケース別（キャンペーン、ロケーション、テクノロジー、セッション、プロファイル、カート、注文、値クエリ）の詳細は：references/recipes.md。

コードからの評価

import croct from '@croct/plug';

const isReturning = await croct.evaluate<boolean>('user is returning').catch(() => false);
const inList = await croct.evaluate<boolean>(
  "context's countries include location's countryName",
  {attributes: {countries: ['United States', 'Canada']}}, // `context's countries` として読み取られます
);

Next.js サーバー： @croct/plug-next/server から await evaluate(query) または await cql`user's persona is in ${roles}` 。React： useEvaluation(query)。HTTP： POST https://api.croct.io/client/web/evaluate、リクエストボディ {"query": "..."}。詳細、属性制限、動的値、推定：references/evaluation.md。

落とし穴とデバッグ

症状	考えられる原因	修正
x is y で構文エラー	is 短縮形は右辺にリテラルが必要	x is equal to y または x == y
location city is "Berlin" で構文エラー	アクセサなし：変数とそのプロパティの間に裸の単語がある	location's cityName、property cityName of location、または location.cityName
"1" > 0 または session's start > "2026-01-01" の比較エラー	関係演算子は型を変換しない	キャスト："1" as number > 0、... > "2026-01-01" as datetime、または is after を使用
ロケーション/コードが決してマッチしない	大文字小文字の誤り：コードは大文字（"US"、"NA"、"CA"）で、文字列は大文字小文字を区別する	大文字を使用、is like、is equal to ... ignoring case、または ~/.../i を使用
matches "Sale" が "sale" にマッチしない	matches、starts with、ends with は大文字小文字を区別する	is like "sale" または matches ~/sale/i
定量子が後続の条件を飲み込む	定量子の述語は最後まで拡張される	定量子全体を括弧で囲む
a or b and c が奇妙に動作する	and は or よりも強く結合する	括弧を追加
条件付き結果が誤って乗算される	条件文は貪欲である	(A if c otherwise B) * price
プロファイル/カート/興味の条件が真にならない	統合必須データが送信されていない	イベントを追跡するか、属性を設定します（croct-track-events スキルを参照）
X is greater than 30 と X is not greater than 30 の両方が偽	未定義値：ブールエラー耐性により偽になる	X is defined and ... または X or else 0 を使用
user is identified が常に偽	サインイン/アップ/アウトイベントが追跡されていない	それらを追跡する。そうしないとユーザーは常に匿名となる
cart.items[2nd]、first of、average of、min of エラー	要素がないか、コレクションが空	or else null / or else 0 を追加
contains none of [] vs contains neither []	空の右辺：none は偽、neither は真	重複なしには contains neither を使用
's と括弧の混在エラー	所有権/属格と括弧には括弧が必要	(cart's items)[1st] またはドット記法 cart.items[*]
イベント式が利用不可	Scale プランの機能	可能な場合はプロファイル/セッション統計を使用する（user's stats' orders）
「推定不可」	page、現在のコンテキスト、または now/today/yesterday を使用している	想定内。オーディエンスは実行時には機能する
範囲エラー	.. 範囲は最大 30 項目	範囲を狭める
変数/パラメータ名エラー	変数は再定義不可。名前は識別子である必要がある	名前を変更する。組み込み名（user、page）や一般的な単語は避ける

推奨事項：

• 非開発者と共有するオーディエンスでは、明示的な is equal to、is greater than を優先する。読みやすい場合は技術スタイルを使用する。
• オプショナルデータは is defined または or else で保護する。
• and チェーンでは安価な条件を最初に配置する（短絡評価により残りをスキップ）。
• contains all / contains none を否定する代わりに、contains either / contains neither を使用する。

禁止事項：

• テスト、変数、イベント表現を発明しないこと。user is new や user has made purchase などの例はドキュメントの散文に登場しますが、文書化された構造ではありません。user is not returning や user's stats' orders is not 0（または user has placed an order）を使用してください。
• location's countryName をコードと比較しないこと。"US" には countryCode を使用してください。
• 算術演算での暗黙の日付変換に依存しないこと："2021-01-01" as date + 1 day。

参考文献

ファイル	読むタイミング
references/syntax.md	字句規則、let、関数、リテラル、アクセサとセレクタ、優先順位テーブル、条件文、期間
references/context-and-data-types.md	すべての変数とプロパティ、利用可能性フラグ、列挙型（デバイスカテゴリ、カートステージ、大陸、ロケーションタグ）、変換
references/expressions.md	すべてのテスト、演算子、エラー耐性、定量子、マクロ、修飾子
references/events.md	イベント式、条件演算子、カウント定量子、時間枠、追跡要件
references/evaluation.md	SDK evaluate / cql / フック、Evaluation API、コンテキスト属性、動的値、オーディエンス推定
references/recipes.md	ユースケース別のすぐに使えるオーディエンスと値クエリ

関連スキル：croct-integrate-sdk（SDK セットアップ）、croct-track-events（クエリが読み取るイベントと属性の送信）、croct-use-api（HTTP API）、croct-model-content（コンテンツ定義内の動的値）、croct-personalize-and-test（オーディエンスを使用するエクスペリエンスと実験）、croct-use-croct（概念とオリエンテーション）。

ライブドキュメント

• インデックス：https://docs.croct.com/llms.txt
• CQL リファレンス：https://docs.croct.com/reference/cql/introduction.md（任意のページに .md を追加）
• 検索：https://docs.croct.com/api/search.md?term=