dt-dql-essentials

DQL の基本スキル

DQL はパイプラインベースのクエリ言語です。クエリでは | でコマンドを連結し、データをフィルタリング、変換、集計します。DQL には SQL とは異なる独自の構文があります。DQL クエリを書く前に、このスキルを読み込んでください。

---

リファレンスを読み込むタイミング

特定のタスクに取り組む前に、関連するリファレンスを読み込んでください。

タスク	必読のリファレンス
データの発見	references/discovery.md
フィールド名、名前空間、データモデル、安定性レベル、クエリパターン	references/semantic-dictionary.md
クエリの最適化 — クエリを高速化／効率化／低コスト化する、消費量とスキャンされるデータを削減する（早期フィルタリング、バケットフィルター、時間範囲、フィールド選択、サンプリング、カーディナリティ）	references/optimization.md
エンティティ間の関係を見つけるための Smartscape トポロジーのナビゲーション	references/smartscape-topology-navigation.md
summarize と makeTimeseries のパターン（バケット化、暦月）	references/summarization.md
配列と時系列の操作（arrayFilter、collectArray、反復処理）	references/iterative-expressions.md
条件ロジック（if/else チェーン）、coalesce、文字列／日付ヘルパー	references/useful-expressions.md
in 演算子（サブクエリ）、@ の時間アラインメント単位の完全な一覧	references/operators.md
matchesValue、matchesPhrase、matchesPattern、in() — 文字列パターンマッチング、正規表現、配列マッチング、ワイルドカード、大文字と小文字の区別	references/string-matching.md

---

DQL リファレンス索引

この索引を使って、関数グループ（例：時間関数、変換）から詳細な仕様へ、または関数名から仕様ファイルへ移動できます。

説明	項目
データ型	array, binary, boolean, double, duration, long, record, string, timeframe, timestamp, uid
パラメーター値の型	bucket, dataObject, dplPattern, entityAttribute, entitySelector, entityType, enum, executionBlock, expressionTimeseriesAggregation, expressionWithConstantValue, expressionWithFieldAccess, fieldPattern, filePattern, identifierForAnyField, identifierForEdgeType, identifierForFieldOnRootLevel, identifierForNodeType, joinCondition, jsonPath, metricKey, metricTimeseriesAggregation, namelessDplPattern, nonEmptyExecutionBlock, prefix, primitiveValue, simpleIdentifier, tabularFileExisting, tabularFileNew, url
コマンド	append, data, dedup, describe, expand, fetch, fields, fieldsAdd, fieldsFlatten, fieldsKeep, fieldsRemove, fieldsRename, fieldsSnapshot, fieldsSummary, filter, filterOut, join, joinNested, limit, load, lookup, makeTimeseries, metrics, parse, search, smartscapeEdges, smartscapeNodes, sort, summarize, timeseries, traverse
関数 — 集計	avg, collectArray, collectDistinct, correlation, count, countDistinct, countDistinctApprox, countDistinctExact, countIf, max, median, min, percentRank, percentile, percentileFromSamples, percentiles, stddev, sum, takeAny, takeFirst, takeLast, takeMax, takeMin, variance
関数 — 配列	arrayAvg, arrayConcat, arrayCumulativeSum, arrayDelta, arrayDiff, arrayDistinct, arrayFirst, arrayFlatten, arrayIndexOf, arrayLast, arrayLastIndexOf, arrayMax, arrayMedian, arrayMin, arrayMovingAvg, arrayMovingMax, arrayMovingMin, arrayMovingSum, arrayPercentile, arrayRemoveNulls, arrayReverse, arraySize, arraySlice, arraySort, arraySum, arrayToString, vectorCosineDistance, vectorInnerProductDistance, vectorL1Distance, vectorL2Distance
関数 — ビット演算	bitwiseAnd, bitwiseCountOnes, bitwiseNot, bitwiseOr, bitwiseShiftLeft, bitwiseShiftRight, bitwiseXor
関数 — ブール値	exists, in, isFalseOrNull, isNotNull, isNull, isTrueOrNull, isUid128, isUid64, isUuid
関数 — キャスト	asArray, asBinary, asBoolean, asDouble, asDuration, asIp, asLong, asNumber, asRecord, asSmartscapeId, asString, asTimeframe, asTimestamp, asUid
関数 — 定数	e, pi
関数 — 変換	toArray, toBoolean, toDouble, toDuration, toIp, toLong, toSmartscapeId, toString, toTimeframe, toTimestamp, toUid, toVariant
関数 — 作成	array, duration, ip, record, smartscapeId, timeframe, timestamp, timestampFromUnixMillis, timestampFromUnixNanos, timestampFromUnixSeconds, uid128, uid64, uuid
関数 — 暗号化	hashCrc32, hashMd5, hashSha1, hashSha256, hashSha512, hashXxHash32, hashXxHash64
関数 — エンティティ	classicEntitySelector, entityAttr, entityName
関数 — 式の時系列集計	avg, count, countDistinct, countDistinctApprox, countDistinctExact, countIf, end, max, median, min, percentRank, percentile, percentileFromSamples, start, sum
関数 — フロー	coalesce, if
関数 — 汎用	jsonField, jsonPath, lookup, parse, parseAll, type
関数 — 取得	arrayElement, getEnd, getHighBits, getLowBits, getStart
関数 — 反復処理	iAny, iCollectArray, iIndex
関数 — 数学	abs, acos, asin, atan, atan2, bin, cbrt, ceil, cos, cosh, degreeToRadian, exp, floor, hexStringToNumber, hypotenuse, log, log10, log1p, numberToHexString, power, radianToDegree, random, range, round, signum, sin, sinh, sqrt, tan, tanh
関数 — ネットワーク	ipIn, ipIsLinkLocal, ipIsLoopback, ipIsPrivate, ipIsPublic, ipMask, isIp, isIpV4, isIpV6
関数 — Smartscape	getNodeField, getNodeName
関数 — 文字列	concat, contains, decodeBase16ToBinary, decodeBase16ToString, decodeBase64ToBinary, decodeBase64ToString, decodeUrl, encodeBase16, encodeBase64, encodeUrl, endsWith, escape, getCharacter, indexOf, lastIndexOf, levenshteinDistance, like, lower, matchesPattern, matchesPhrase, matchesRegex, matchesValue, punctuation, replacePattern, replaceString, splitByPattern, splitString, startsWith, stringLength, substring, trim, unescape, unescapeHtml, upper
関数 — 時刻	formatTimestamp, getDayOfMonth, getDayOfWeek, getDayOfYear, getHour, getMinute, getMonth, getSecond, getWeekOfYear, getYear, now, unixMillisFromTimestamp, unixNanosFromTimestamp, unixSecondsFromTimestamp
関数 — メトリクスの時系列集計	avg, count, countDistinct, end, max, median, min, percentRank, percentile, start, sum

---

Syntax Pitfalls

❌ 誤り	✅ 正しい	問題点
filter field in ["a", "b"]	filter in(field, {"a", "b"})	DQL では、[ と ] はサブクエリを囲みますが、静的な配列リテラルは囲みません。静的な値には {} または array() を使用してください。
filter: { in(field, [sub-query]) }（例：timeseries filter: 内）	filter: { field in [sub-query] }	in() は引数として実行ブロックを受け付けません。右辺がサブクエリ（実行ブロック）の場合は、in 演算子を使用してください：field in [execution block]。
by: severity, status	by: {severity, status}	by: 句（summarize、makeTimeseries など）でフィールドのリストを指定する場合は、中括弧で囲む必要があります。
contains(toLowercase(field), "err")	contains(field, "err", false)	大文字と小文字を区別しない照合に lower() を使わないでください。contains() には、組み込みの第3位置引数 caseSensitive があります（デフォルトは true）。
filter name == "*serv*9*"	filter matchesValue(name, "*serv*") and matchesValue(name, "*9*")	== はワイルドカードをサポートしていません。matchesValue() は * ワイルドカードをサポートしますが、パターンの先頭または末尾にしか指定できません。文字列の途中にあるワイルドカードの意図は、複数の呼び出しに分けて and で結合してください。
文字列フィールドに対する matchesValue(field, "prod")	contains(field, "prod")	ワイルドカードがない場合、matchesValue() は完全一致（大文字と小文字は区別しない）を行うため、"production" は見つかりません。部分文字列の照合には contains() を使用してください（ワイルドカード照合には matchesValue(field, "*prod*") を使用します）。
iAny(matchesValue(arr[], "x") OR matchesValue(arr[], "y"))	matchesValue(arr, {"x", "y"})	matchesValue は、第1パラメーターに配列フィールド、第2パラメーターに配列リテラル {} を受け取ります。iAny や [] は不要です。同じフィールドに対する複数の contains(f, x) OR contains(f, y) をまとめる場合も同様です：matchesValue(f, {"*x*", "*y*"}) を使用してください。
iAny(matchesPhrase(arr[], "phrase"))	matchesPhrase(arr, "phrase")	matchesPhrase は配列フィールドをネイティブに反復処理するため、iAny( と [] を省略できます。注：第2パラメーターは静的な文字列である必要があります。matchesPhrase(f, array("a","b")[]) は実行時エラーになります。
短い、または一般的なトークンに対する contains(field, "pip")	matchesPhrase(field, "pip")	contains は純粋な部分文字列照合です。"pip" は "pipenv" や "gripping" にも一致します。matchesPhrase は文字列をトークン化して単語全体のみを照合するため、誤検知を減らせます。
iAny(in(lower(arr[]), array("a", "b")))	matchesValue(arr, {"a", "b"}, caseSensitive: false)	matchesValue はデフォルトで大文字と小文字を区別しないため、lower()、in()、iAny のラッパーは不要です。ここで caseSensitive: false を明示しているのは、置き換え前の lower() の意図を示すためだけです。
2つの別々の配列を反復処理する iAny(f1[] == "a" AND f2[] == "b")	in(f1, "a") AND in(f2, "b")	複数配列に対する iAny は直積ではなくペアごとに評価されます。f1[] の要素 i は、f2[] の要素 i と照合されます。配列の長さが異なる場合、結果は null です。代わりに独立した in() チェックを使用してください。references/iterative-expressions.md を参照してください。
toLowercase(field)	lower(field)	関数名は toLowercase() ではなく lower() です。to 接頭辞を使うのは型変換関数（toString()、toLong() など）だけです。
arrayAvg(field[]) または arraySum(field[])	arrayAvg(field) または field[]	field[] = 要素単位の反復式（配列→配列）、arrayAvg(field) = スカラーへの集約（配列→単一の値）です。両者を混在させないでください。arrayAvg(field[]) は意味的に誤りです。
lookup または join の後の my_field	lookup.my_field / right.my_field	lookup は、追加フィールドにデフォルトで lookup. 接頭辞を付けます（prefix: で変更可能）。join は右側のフィールドに right. 接頭辞を付けます。
substring(field, 0, 200)	substring(field, from: 0, to: 200)	第1パラメーター（式）は位置引数ですが、from: と to: は名前付きの省略可能なパラメーターであり、名前を含める必要があります。
filter host = "A"	filter host == "A"	DQL では等価比較に = ではなく == を使用します。単一の = は代入です（例：fieldsAdd、summarize のエイリアス）。
fetch logs, from: toTimestamp('2026-01-01')	fetch logs, from: -24h	from: / to: には期間リテラル（例：-24h、-7d）または now() 式を指定できます。toTimestamp() は指定できません。絶対範囲には timeframe: "start/end"（ISO 8601）を使用してください。
filter log.level == "ERROR"	filter loglevel == "ERROR"	ログの重大度フィールドは loglevel（ドットなし）です。log.level は存在しません。
sort count() desc	sort `count()` desc	特殊文字（括弧など）を含むフィールドは、バッククォートで囲む必要があります。
length(field)	stringLength(field)	DQL の文字列長関数は stringLength です。length() はありません。
metrics dt.host.cpu.usage	timeseries avg(dt.host.cpu.usage)	metrics はメトリクスのメタデータを読み込みますが、値は読み込みません。データには timeseries を使用してください。
join [...], on:{left.a.b == right.a.b}	join [...], on:{left[`a.b`] == right[`a.b`]}	join/lookup 条件のドットを含むフィールド名には、バッククォート付きのブラケット記法が必要です。
fieldsSummary（引数なし）	fieldsSummary field1, field2	fieldsSummary には、少なくとも1つのフィールドパラメーターが必要です。
percentile／median／percentRank を使用した timeseries — 結果なし	timeseries コマンドに rollup: avg（または min／max／sum）を追加する	これら3つの関数は、ゲージ／カウントメトリクスで rollup: が必須です。指定しないと、クエリはエラーを出さずに空の結果を返します。
summarize p95 = percentile(duration, 95, rollup: avg)	summarize p95 = percentile(duration, 95)	rollup: は timeseries 専用のパラメーターです。ログ／スパン／イベントに対する summarize 内の同名の集計では、UNKNOWN_PARAMETER_DEFINED エラーが発生します。rollup: を追加するのは、timeseries 内で メトリクス を集計する場合だけです。
filter array.contains(field, "v") または arrayContains(field, "v")	filter in(field, {"v"})	どちらの関数も DQL にはありません。Python／Java／SQL からの幻覚です。in() は 配列型フィールド（例：dt.davis.problems の k8s.namespace.name）をネイティブに照合します。needle のいずれかの要素が haystack のいずれかの要素と一致すると、true を返します。references/iterative-expressions.md を参照してください。
フィールドが配列型の場合の filter k8s.namespace.name == "ns"	filter in(k8s.namespace.name, {"ns"})	配列型フィールドに対する == は何にも一致しません。エラーを出さずに0行を返すため、誤りではなく「データがない」ように見えます。dt.davis.problems では k8s.* フィールドは配列です。完全一致には in()、または matchesValue(field, {...}) を使用してください。
parseJson(field) または extractJsonField(field, jsonPath: "$.x")	parse field, "JSON:parsed" の後に parsed[x]	どちらの関数も存在しません。文字列フィールドに埋め込まれた JSON は、parse コマンドと JSON DPL マッチャーで展開し、ブラケット記法でアクセスします。
filter hour(timestamp) == 4 / minute(timestamp)	filter getHour(timestamp) == 4 / getMinute(timestamp)	hour()／minute() 関数はありません。get* ファミリーは数値を返すため、数値比較や範囲指定が可能です。formatTimestamp(timestamp, format: "HH") で代用しないでください。これは文字列を返すため、== 4 は一致なしとして処理されます。
dt.entity.* に対する fields fromRelationships, toRelationships, containerImageTag	まず describe dt.entity.<type> を実行し、その後、実在するフィールドを選択する	従来型のエンティティオブジェクトは、Entities REST API の属性名を公開しません。フィールド名は API ペイロードから推測するのではなく、describe <dataObject> で確認する必要があります。
by: {bin(timestamp, 1h)} の後に sort `bin(timestamp,1h)`	by: {t = bin(timestamp, 1h)} の後に sort t	DQL は自動生成されたグループキー名を、式の記述方法に関係なく、カンマの後にスペースを入れた bin(timestamp, 1h) に正規化します。スペースを省略したバッククォート付き参照は FIELD_DOES_NOT_EXIST エラーになります。グループキーには必ずエイリアスを付けてください。
fetch spans | ... by: {bin(timestamp, 1h)}	fetch spans | ... by: {t = bin(start_time, 1h)}	spans に timestamp フィールドはありません。時間フィールドは start_time と end_time です。timestamp を参照すると、位置によってエラーになるか、null が返されます。
lookup [...], fields: {`dotted.name`}	lookup [...], fields: {dotted.name}	lookup の fields: パラメーター内でフィールド名をバッククォートで囲まないでください。PARSE_ERROR が発生します。
data record(key: "val")	data record(key = "val")	record() の名前付きフィールドには : ではなく = を使用します。: は rollup: などのコマンドパラメーターに使います。
getNodeField(dt.smartscape.host, "tags")["tag.key"]	getNodeField(dt.smartscape.host, "tags")[tag.key]	このタグマップへのアクセスパターンでは、ブラケット内のキーに引用符なしの識別子構文を使用する必要があります。引用符で囲むと、パースエラーになります。
by: {dt.entity.host} または dt.entity.*	by: {dt.smartscape.host} または dt.smartscape.*	dt.entity.* は非推奨です。新しいクエリでは必ず dt.smartscape.* を使用してください。

---

Fetch コマンド → データモデル

DQL クエリは fetch <data_object> または timeseries で始まります。fetch dt.metric はありません。メトリクスには timeseries を使用します。

Fetch コマンド	データモデル	主なフィールド／注記
fetch spans	分散トレーシング	span.*、service.*、http.*、db.*、code.*、exception.*
fetch logs	ログイベント	log.*、k8s.*、host.* — メッセージ本文は content、重大度は loglevel です（log.level ではありません）
fetch events	DAVIS／インフライベント	event.*、dt.smartscape.*
fetch bizevents	ビジネスイベント	event.*、カスタムフィールド
fetch security.events	セキュリティイベント	vulnerability.*、event.*
fetch user.sessions	RUM セッション	dt.rum.*、browser.*、geo.*
fetch user.events	RUM 個別イベント	ページビュー、クリック、リクエスト、エラー
fetch user.replays	セッションリプレイの記録
fetch application.snapshots	アプリケーションスナップショット
fetch dt.davis.events	Davis が検出したイベント
fetch dt.davis.problems	Davis が検出した問題
timeseries avg(metric.key)	メトリクス	fetch ではありません — ハイフンを含むキーにはバッククォートが必要です：timeseries sum(`my.metric-name`)
smartscapeNodes "HOST"	トポロジー	fetch ではありません — タイプ：HOST、SERVICE、K8S_CLUSTER など

dt.entity.* は非推奨です。新しいクエリでは dt.smartscape.* と smartscapeNodes を使用してください。

利用可能なすべてのデータオブジェクトを確認するには：fetch dt.system.data_objects | fields name, display_name, type

→ フィールドの名前空間の詳細については、references/semantic-dictionary.md を参照してください。

---

samplingRatio パラメーター

fetch は samplingRatio: パラメーターに対応しており、読み取るデータ量を削減できます。大規模なデータセットでクエリのパフォーマンスを向上させるのに便利です。

fetch spans, samplingRatio:100   // reads ~1% of data

許可される値： 対象のデータオブジェクトによって異なり、1、10、100、1000、10000 から 100000 までです。最高レベルは logs と spans でのみ利用できます。

サンプリングは spans、user.events、user.sessions では階層的です。高い比率（例：100）で含まれるレコードは、低い比率（例：10、1）にも必ず含まれますが、その逆は保証されません。つまり、比率ごとの結果は互いに部分集合になります。それ以外のメトリクス以外のデータオブジェクトでは、各レコードが独立してサンプリングされるため、比率ごとの結果は部分集合になりません。

実際に適用された比率は dt.system.sampling_ratio フィールドから確認できます。サンプリングされた件数を真の合計に換算するには、このフィールドを使用します。

fetch logs, samplingRatio:10
| summarize count_extrapolated = sum(dt.system.sampling_ratio)

---

時系列の集計関数

timeseries コマンドがサポートする集計関数は、次のもののみです。

関数	説明
sum	時間枠ごとのメトリクスデータポイントの合計
avg	時間枠ごとのメトリクスデータポイントの平均
min	時間枠ごとのメトリクスデータポイントの最小値
max	時間枠ごとのメトリクスデータポイントの最大値
count	時間枠ごとのメトリクスデータポイント数
percentile(metric, N)	時間枠ごとの N パーセンタイル。rollup: が必要です — 下記を参照してください。
median(metric)	時間枠ごとの 50 パーセンタイル（= percentile(metric, 50)）。rollup: が必要です。
percentRank(metric, value)	時間枠ごとの値のパーセンタイルランク。rollup: が必要です。
countDistinct(metric)	時間枠ごとの近似ユニーク数（カーディナリティメトリクスのみ。rollup: は指定できません）。

ヘルパー（集計と併用）：start()、end()。

timeseries ではサポートされていません： countIf、collectArray、stddev、variance、takeAny、takeFirst、takeLast — summarize または makeTimeseries を使用してください。

rollup: パラメーター

メトリクスは取り込み時に事前集計されます。rollup: は、各時間枠で生データポイントをどのように統合するかを制御します。percentile、median、percentRank では必須です。指定しない場合、クエリはエラーを返さずに結果を返しません。avg／min／max／sum／count は rollup: なしで動作します。

rollup: は timeseries 専用のパラメーターです。メトリクス集計にのみ使用できます。イベントデータ（ログ、スパン、イベント）を対象に summarize で使用できる、同名の集計関数では受け付けません。summarize p95 = percentile(duration, 95, rollup: avg) は UNKNOWN_PARAMETER_DEFINED エラーになります。summarize では、rollup: を指定せずに percentile(field, N) を使用してください。

単一の集計では、コマンドレベルで rollup: を指定します。複数の集計を {} で指定する場合、rollup: は各関数呼び出しの内側に指定する必要があります（コマンドレベルの rollup: を指定すると UNKNOWN_PARAMETER_DEFINED エラーになります）。

timeseries p90 = percentile(dt.process.handles.file_descriptors_percent_used, 90), rollup: avg

timeseries {
  p90 = percentile(dt.process.handles.file_descriptors_percent_used, 90, rollup: avg),
  med = median(dt.process.handles.file_descriptors_percent_used, rollup: avg),
  avg_val = avg(dt.process.handles.file_descriptors_percent_used)
}, by: {dt.smartscape.host}

値：avg（ゲージ）、min、max、sum（カウンター）、total。

時系列からスカラーへの変換

時系列をスカラーに変換する方法は 2 つあります。集計値を 1 つだけ必要とする場合は、scalar:true パラメーターを使用してください。配列が生成されないため、より効率的です。同じクエリで完全な時系列とそこから導出したスカラーの両方が必要な場合は、配列関数を使用してください。

推奨：集計関数で scalar:true を指定する

任意の時系列集計関数に scalar:true を渡します。結果フィールドには配列ではなく単一の値が格納され、中間配列も割り当てられません。

timeseries avg_cpu = avg(dt.host.cpu.usage, scalar:true), by:{dt.smartscape.host}

timeseries {
  avg_cpu = avg(dt.host.cpu.usage, scalar:true),
  max_cpu = max(dt.host.cpu.usage, scalar:true)
}, by:{dt.smartscape.host}

代替方法：fieldsAdd で配列関数を使用する

派生スカラーとともに時系列全体の配列も必要な場合は、後続の | fieldsAdd で配列関数を使用します。

関数	説明
arrayAvg(arr)	配列内のすべての値の平均
arraySum(arr)	すべての値の合計
arrayMin(arr)	最小値
arrayMax(arr)	最大値
arrayMedian(arr)	中央値
arrayPercentile(arr, N)	第 N 百分位数（0～100）
arrayLast(arr)	null 以外の最後の値（最新のデータポイント）
arrayFirst(arr)	null 以外の最初の値（最も古いデータポイント）

timeseries cpu = avg(dt.host.cpu.usage), by:{dt.smartscape.host}
| fieldsAdd avg_cpu = arrayAvg(cpu), max_cpu = arrayMax(cpu)

---

時刻のアラインメント（@ 演算子）

@ 演算子はタイムスタンプを境界に合わせます。エージェントが間違えやすい箇所です。

式	意味
now()@h	現在時刻を時間境界に合わせます
now()@d	今日の午前 0 時
now()@w1	今週の月曜日
now()-2h@h	2 時間前の時刻を時間境界に合わせます（先にオフセットし、その後にアラインメント）

ルール：

• 順序：アラインメントより前にオフセットを指定します。now()-2h@h とし、now()@h-2h とはしません
• @ と単位の間にスペースを入れません。now()@h とし、now() @h とはしません
• m は分、M は月です。混同しないでください

→ timeseries 集計と rollup: のルールの全一覧は、references/dql/dql-functions-timeseries.md を参照してください → arrayAvg／arrayMax／arrayPercentile／…の仕様は、references/dql/dql-functions-array.md を参照してください

---

エンティティと Smartscape のパターン

エンティティのフィールドはタイプごとにスコープが設定されています。entity.id は存在しません。トポロジーのクエリには smartscapeNodes を使用してください。

エンティティ	データ内の ID フィールド	smartscapeNodes のタイプ
ホスト	dt.smartscape.host	"HOST"
サービス	dt.smartscape.service	"SERVICE"
プロセス	dt.smartscape.process	"PROCESS"
K8s クラスター	dt.smartscape.k8s_cluster	"K8S_CLUSTER"

文字列から ID を変換するには toSmartscapeId() を使用してください（必須です！）。

→ references/smartscape-topology-navigation.md

---

makeTimeseries コマンド

makeTimeseries は、イベントデータ（ログ、スパン、bizevents）から時間バケットごとの系列を作成します。事前に取り込まれたメトリクスをクエリする timeseries とは異なり、makeTimeseries はパイプライン内でデータを集計します。

timeseries を直接 makeTimeseries にパイプしないでください。INVALID_IMPLICIT_TIME_DEFAULT で失敗します。メトリクスデータを再集計するには、start() + expand を使用してください（references/summarization.md を参照）。

fetch logs
| makeTimeseries
    total = count(),
    errors = countIf(loglevel == "ERROR"),
    interval: 5m,
    by: {k8s.cluster.name}
| fieldsAdd error_rate = errors[] * 100.0 / total[]

主なパラメーター：interval:、by:{}、from:／to:、bins:、time:（タイムスタンプフィールド）、spread:（count／countIf のみ）、nonempty:。

→ makeTimeseries のパターンと summarize のバケット化の詳細は references/summarization.md を参照してください。 → 時系列配列の操作については references/iterative-expressions.md を参照してください。

---

文字列マッチング関数

DQL には、文字列と配列のパターンマッチング用の主な関数が 4 つあります。詳しいガイドとクイックリファレンステーブルについては、references/string-matching.md を参照してください。

• matchesValue(field, {"pattern*", "*other*"}) — ワイルドカードマッチング（先頭／末尾の *）。第 1 パラメーターには配列フィールド、第 2 パラメーターには配列リテラル {} を指定できます。iAny や [] は不要です。デフォルトでは大文字と小文字を区別しません（大文字と小文字を区別するには caseSensitive: true を指定します）。contains() と iAny を組み合わせる方法や、lower() を使った回避策の代わりになります。
• matchesPhrase(field, "token") — 文字列をトークン化して単語全体にマッチします。部分文字列にそのままマッチする contains() とは異なります。第 1 パラメーターは配列フィールドをネイティブに受け付けます。第 2 パラメーターは静的な文字列である必要があります（配列の展開により実行時エラーが発生します）。
• in(field, array("a", "b")) — セットへの所属判定です。両方のパラメーターが配列を受け付けるため、重複／積集合のチェックとして使用できます。

---

連鎖 Lookup パターン

fields パラメーターを指定しない lookup コマンドは、新しいフィールドを追加する前に、プレフィックス（デフォルト：lookup.）で始まる既存のフィールドをすべて削除します。複数の lookup を連鎖させる場合は、結果を保持するために fields パラメーターまたはカスタムプレフィックスを使用してください。

オプション 1（デフォルト）：必要なフィールドがわかっている場合。

fetch bizevents
// Step 1: First lookup — enrich orders with product info
| lookup [fetch bizevents
    | filter event.type == "product_catalog"
    | fields product_id, category],
  sourceField: product_id, lookupField: product_id, fields: {product_id, product_category = category}

// Step 2: Second lookup — specify fields with a different name
| lookup [fetch bizevents
    | filter event.type == "warehouse_stock"
    | fields category, warehouse_region],
  sourceField: product_category, lookupField: category, fields: {warehouse_region, warehouse_category = category}

product_id、product_category、warehouse_region、warehouse_category の 4 つの lookup フィールドがすべて使用可能です。 fields:{...} パラメーターを指定しない場合、フィールドには lookup. というプレフィックスが付き、2 つ目の lookup コマンドによって 1 つ目のコマンドで追加されたフィールドが削除されます。

オプション 2：lookup のすべてのフィールドを保持する場合。

fetch bizevents
// Step 1: First lookup — enrich orders with product info
| lookup [fetch bizevents
    | filter event.type == "product_catalog"
    | fields product_id, category],
  sourceField: product_id, lookupField: product_id, prefix: "product."

// Step 2: Second lookup — specify fields with a different prefix
| lookup [fetch bizevents
    | filter event.type == "warehouse_stock"
    | fields category, warehouse_region],
  sourceField: product_category, lookupField: category, prefix: "warehouse."

新しいフィールドは product.product_id、product.category、warehouse.category、warehouse.warehouse_region です。 product. または warehouse. で始まるすべてのフィールドが元のソースから削除されます。 専用の prefix を指定しない場合、どちらの lookup コマンドも同じプレフィックス（lookup.）を使用するため、2 つ目の lookup によって 1 つ目の lookup の結果が削除され、フィールドが空になります。

---

makeTimeseries コマンド

makeTimeseries は、イベントデータ（ログ、スパン、bizevents）から時間バケット単位の系列を構築します。事前に取り込まれたメトリクスをクエリする timeseries とは異なり、makeTimeseries はパイプライン内でデータを集計します。

timeseries を直接 makeTimeseries にパイプしないでください — INVALID_IMPLICIT_TIME_DEFAULT エラーが発生します。メトリクスデータを再集計するには、start() + expand を使用してください（references/summarization.md を参照）。

fetch logs
| makeTimeseries
    {total = count(),
    errors = countIf(loglevel == "ERROR")},
    interval: 5m,
    by: {k8s.cluster.name}
| fieldsAdd error_rate = errors[] * 100.0 / total[]

主なパラメーター：interval:、by:{}、from:/to:、bins:、time:（タイムスタンプフィールド）、spread:（count/countIf のみ）、nonempty:。完全な仕様については、references/dql/dql-commands.md を参照してください。

spread: を使用したエンティティ存在タイムライン：

smartscapeNodes "HOST"
| makeTimeseries concurrently_existing_hosts = count(), spread: lifetime

時系列配列の操作については、references/iterative-expressions.md を参照してください。

---

時間範囲の指定

データにアクセスするには、時間範囲を指定する必要があります。 UI、REST API のパラメーター、または DQL クエリで from: と to: のペアを明示的に使用して指定できます（いずれかを省略した場合は now() がデフォルトになります）。または、単一の timeframe: パラメーターを使用することもできます。 時間範囲は、絶対値または現在時刻を基準とする相対式で表現できます。時間調整演算子（@）を使用すると、タイムスタンプを時間単位の境界に丸めることができます。詳細については、references/operators.md を参照してください。

例

from:now()-1h@h, to:now()@h     // last complete hour

from:now()-1d@d, to:now()@d     // yesterday complete

from:now()@M                    // this month so far, till now

from:now()-2h@h                 // go back 2 hours, then align to hour boundary

@ の調整単位の一覧表全体（m と M の違い、曜日のバリエーション w1～w7、@3h のような係数の規則を含む）については、references/operators.md を参照してください。

絶対タイムスタンプ

ISO 8601 形式を使用します：

from:"2024-01-15T08:00:00Z", to:"2024-01-15T09:00:00Z"

---

時刻の変更

主な概念

• DQL には、時刻に関連する特殊な型が 3 つあります：
  • timestamp — 内部ではエポックからのナノ秒数として保持されますが、特定のタイムゾーンの日付／時刻として公開されます
  • timeframe — 2 つのタイムスタンプ（開始と終了）のペアです
  • duration — 内部ではナノ秒数として保持されますが、適切な係数（例：ms、分、日）でスケーリングされた時間の長さとして公開されます

ルール

• タイムスタンプを減算すると、時間の長さが得られます：timestamp - timestamp → duration
• 時間の長さを時間の長さで割ると、double が得られます：例：2h / 1m = 120.0
• スカラーと時間の長さの積は、時間の長さになります：例：no_of_h * 1h → duration
• 時刻の要素（時間、月の日など）を抽出する場合：
  • ✅ 時間関数を使用してください。これらの関数は、DST を含むカレンダーとタイムゾーンを適切にサポートします。
  • ❌ 時刻の要素を抽出するために formatTimestamp を使用するのは避けてください。
  • ❌ タイムスタンプと時間の長さを double/long に変換し、除算、剰余、および時間単位をナノ秒で表す定数を使用するのは避けてください。

参照資料

• references/useful-expressions.md — DQL の便利な式
• references/semantic-dictionary.md — Dynatrace セマンティック辞書：フィールドの名前空間、データモデル、安定性レベル、クエリパターン、ベストプラクティス
• references/summarization.md — summarize コマンドと makeTimeseries コマンドのさまざまな使用例
• references/iterative-expressions.md — DQL を使用した配列と時系列の操作（作成、変更、フィルターでの使用）
• references/smartscape-topology-navigation.md — Smartscape のトポロジーをナビゲートする構文とパターン
• references/optimization.md — DQL クエリの最適化：クエリを高速化し、効率を高め、実行コストを削減する方法（実行ごとの消費量／スキャンデータ量の削減）— フィルターの配置、バケットフィルター、時間範囲、フィールド選択、サンプリング、カーディナリティ、パフォーマンスのベストプラクティス
• references/operators.md — in 演算子（サブクエリ構文）と @ 時刻アラインメント単位の完全なリファレンス
• references/discovery.md - データの検出