検索言語の構文
このトピックでは、独自の問合せを作成できるように、構文とルールの説明など、検索の問合せ言語の基本について説明します。問合せは特定のリソース・タイプに検索条件を適用して、結果をソートできるようにします。問合せ言語を使用すると、検索パラメータをより細かく明確に制御できるため、問合せを正確に変更すると異なる結果が生成される可能性がある場合に特に役立ちます。
サポートされているすべてのリソース・タイプおよびリソース属性にわたって検索し、検索結果の順序付けを必要としない場合、またはコンソール・インタフェースを使用して検索パラメータを指定する場合は、問合せを作成する必要はありません。かわりに、検索に問合せ言語構文を適用せずに、フリーフォーム・テキストの部分一致または正確な一致を検索できます。
問合せを実行する準備ができている場合は、手順については、リソースの問合せを参照してください。
問合せの基本
次の例は、問合せの基本構文を示しています。
比較演算子を使用する条件文で記述されている1つ以上の条件を満たすリソースを問い合せるには:
query <resourceType> resources where <conditions>1つ以上の条件を満たし、かつソートされたリソース属性を結果に含めるリソースを問い合せるには:
query <resourceType> resources return <fieldName> where <conditions> sorted by <fieldName> <order>
または、指定した内容に一致する値を持つ属性を持つリソースをクエリーするには:
query <resourceType> resources return <fieldName> matching <keywords>
検索では、空白、インデントおよび改行は無視されます。問合せの例には、読みやすくするためのインデントが含まれています。構文のみを説明する目的で、山カッコ(<>)とイタリック体のテキストは変数を示します。これは1つ以上のキーワードで構成されます。
問合せには、次の句が含まれます。
query- (必須)後続の句に基づいて、どのリソースを返すかを選択します。問合せ文は常にqueryという語で始まります。return-検索結果の拡張ビューまたは拡張ビューに含めるリソース属性を指定します。詳細は、Return Attributesを参照してください。where- リソースと指定されたconditionsを照合します。詳細は、条件を参照してください。matching- テキストが完全に一致するか、リソース・タイプと一致するか、または索引付けられたリソース属性に出現するかに関係なく、リソースを指定されたテキストと照合します。詳細は、「一致」を参照してください。sorted by-orderで指定された順序でfieldNameに従ってリソースを順序付けします。この句を指定しない場合、検索によって作成日が降順でリストされ、最新のリソースが最初にリストされます。詳細は、ソートを参照してください。
それ以外の場合は、句はオプションです。照合の目的で、where句とmatching句を別々にまたは一緒に使用できます。
query句には、次の情報を指定します。
-
resourceType- (必須)問合せを実行するときに、次の句が適用されるリソース・タイプを指定します。リソース・タイプ名(databaseまたはgroupなど)またはallのいずれかを指定できます。allを指定すると、検索によって、すべてのリソース・タイプにわたる指定されたconditionsの一致が検索されます。個々のリソース・タイプについて問合せを実行できますが、ファミリ・タイプについては問合せできません。サポートされるリソース・タイプのリストは、検索の概要のサポートされるリソースの項を参照してください。 resources- (必須)送信するテキストがリソース問合せであることを指定します。
「戻る」の属性
SDKまたはCLIのユーザーの場合、return句は、問合せによって返される検索結果に含める拡張リソース属性を示します。return句を使用すると、検索結果で特定のリソース属性またはすべてのリソース属性を強制的に返すことができ、各リソースの詳細を確認できます。
デフォルトでは、検索結果には、一致するリソースの限定された共通リソース属性セットが表示されます。コンソールでは、これらのリソース属性には、表示名、リソース・タイプ、OCID、コンパートメント、ライフサイクル状態および作成された時間が含まれます。SDKまたはCLIでは、基本的なリソース検索結果に、可用性ドメインおよびリソースに関連付けられたタグも含まれます。問合せで共通リソース属性以外の一致が検出されると、展開された検索結果には、基本結果とともに特定の一致する属性が含まれ、強調表示されます。return句を使用すると、問合せが参照するリソース属性の一致を明示しない場合でも、検索結果の一致に関する詳細を取得できます。
問合せでは、return句は次のもので構成されます。
return <fieldName>fieldNameキーワードは、リソースの属性を識別します。たとえば、問合せの対象とするリソース・タイプがインスタンスの場合、shapeを指定すると、一致するすべてのインスタンスのシェイプが表示されます。(インスタンスの場合のみ、fieldNameは、インスタンスのVNICアタッチメントのプライベートIPアドレスなど、関連リソースの属性を識別できます。attachedVnic.privateIpを指定すると、VNICとインスタンス間のアタッチメントのプライベートIPアドレスを表示することを示します。)
特定のリソースで使用可能な追加の詳細は、そのリソース・タイプに対して索引付けされたリソース属性によって異なります。リソース・タイプのすべての索引付きリソース属性の名前を検索するには、SDKまたはCLIを使用して、return句を含む問合せを実行しますが、フィールド名を指定するかわりに、allAdditionalFieldsを表示するように指定します。例:
query instance resources return allAdditionalFieldsこの問合せでは、インスタンス・リソース・タイプのすべての索引付きリソース属性を表示するレスポンスが生成されます。(コンソールでは、リソース・タイプ・フィルタの適用時にインスタンス・リソースを除き、これらの他のフィールドは表示できません。そのため、SDKまたはCLIを使用して情報を取得する必要があります。)検索結果では、使用可能な追加詳細(およびその情報の構造)は、一致するリソース・タイプによって異なります。さらに、問合せで表示するようにリクエストしたリソース属性を表示するには、必要な権限が必要です。
return句をwhere句と組み合せて、1つ以上の条件を適用しながら、特定の詳細の結果を取得できます。例:query instance resources return allAdditionalFields where assignedEntityType = 'PRIVATE_IP'この問合せでは、PRIVATE_IPの値を持つassignedEntityTypeフィールドを持つすべてのインスタンス・リソースのすべての索引付きリソース属性を表示するレスポンスが生成されます。
制限事項
return句は、一度に1つのリソース・タイプに対してのみ使用できます。return句を含めると、問合せで複数のリソース・タイプを指定することはできません。ただし、必要に応じて、特定のリソース・タイプに対して返される複数のフィールドを指定できます。
同じ問合せにallAdditionalFieldsキーワードと個々のフィールド名の両方を含めることはできません。allAdditionalFieldsキーワードを指定することも、カンマで区切って個々のフィールド名を指定することもできます。
条件
where句は、検索で戻される結果をフィルタ処理するconditionsを適用します。1つ以上の条件文を指定できます。複数条件の詳細は、条件のグループ化を参照してください。
問合せでは、conditionsは次のように構成されています。
<fieldName> <operation> <value>fieldNameキーワードは、その属性のoperationおよび選択されたvalueが評価されるリソース属性です。各フィールドはフィールド・タイプに関連付けられます。フィールド・タイプは、そのフィールドの任意の値に必要な書式を示します。conditions文で使用できるoperationの種類は、フィールド・タイプによって異なります。
問合せconditionsのoperationは、文のvalueに適用される比較演算子です。valueキーワードは、指定したfieldNameの値を参照します。検索は、指定した選択したリソース・タイプの属性が、操作に応じてvalueと一致するかまたは一致しないかを評価します。問合せでは、文字列または日時の値をストレート一重引用符(「)または二重引用符(」)で囲みます。
次の表に、リソース問合せでサポートされる操作を示します。
| 処理 | 説明 | サポートされるフィールド・タイプ | 大/小文字区別? | 例 |
|---|---|---|---|---|
=
|
文字列と等しい、または文字列と完全一致 |
文字列、整数、論理、ブール、日時 |
いいえ |
valueがˈbackUpˈである場合、「backup」、「BACKUP」、「BackUp」、「backUp」またはその他のバリエーションと一致します。 |
!=
|
次と等しくない |
文字列、整数、論理、ブール、日時 |
いいえ |
valueがˈbackUpˈであれば、「backUp」、「backup」またはその他のバリエーションと等しくないすべてと一致します。また、その順序に'backup'という文字が含まれないものも一致します。 |
==
|
厳密に等しい |
文字列 |
はい |
valueがˈbackUpˈの場合は、「backUp」と一致するのみで、他のバリエーションは一致しません。 |
!==
|
厳密に次に等しくない |
文字列 |
はい |
valueがˈbackUpˈであれば、「backup」、「BACKup」または「backUp」以外のものすべてと一致します。 |
=~
|
含む |
文字列 |
いいえ |
valueがˈbackUpˈであれば、「backup」、「BACKUP」、「BackUp」、「backUp」またはその他のバリエーションと同じか、他の文字とともにこの順序で指定した文字を含むすべてと一致します。 |
>=
|
以上 |
整数、論理、日時 |
該当なし |
条件としてsize >= 5がある問合せでは、すべての結果のsizeフィールドに5以上の値が含まれます。 |
>
|
次より大きい |
整数、論理、日時 |
該当なし |
条件としてsize > 5がある問合せでは、すべての結果のsizeフィールドに5より大きい値が含まれます。 |
<=
|
以下 |
整数、論理、日時 |
該当なし |
条件としてsize <= 5がある問合せでは、すべての結果のsizeフィールドに5以下の値が含まれます。 |
<
|
次より小さい |
整数、論理、日時 |
該当なし |
条件としてsize < 5がある問合せでは、すべての結果のsizeフィールドに5以下の値が含まれます。 |
次の表に、サポートされているフィールド・タイプの各カテゴリに属するリソース属性の例を示します。(前述のように、フィールド型は、指定されたフィールドに必要な形式と、conditions文でペアにできるoperationの種類を示します。)
表には、特定のフィールド・タイプの考えられるすべての例が含まれず、すべてのリソース・タイプの例も含まれていません。検索サービスで特定のリソース属性に想定される書式を知りたい場合は、コマンドライン・インタフェースまたはAPIを使用してリソース属性の詳細を確認できます。APIのドキュメントを参照することもできます。APIドキュメントには、属性、そのフィールド・タイプおよび制限を指定する、サポートされている各リソース・タイプのリファレンスが含まれています。詳細は、検索の概要のサポートされるリソースの項を参照してください。
| タイプ | リソース属性の例 |
|---|---|
| 文字列 | 表示名、ライフサイクル状態、可用性ドメイン、タグ、CIDRブロックおよびURL |
| 整数 | リソースのサイズまたは長さ |
| Rational | 使用可能なデータ・ストレージ |
| Boolean | 機能が有効か構成されているか、リソースが正常かどうか、リソースがパブリックかプライベートか、最新バージョンかどうか、および何かが許可されているかどうか |
| 日付/時間 | 作成日、最終更新日、最終索引付き日付およびスケジュール済メンテナンスの再起動 |
条件のグループ化
1つの問合せに複数の条件文を含めることで、いくつかの条件に従って結果を絞り込むことができます。論理演算子&&(論理ANDを示すアンパサンド)、||(論理ORを示す縦棒)または論理IN演算子を使用して、条件をグループ化できます。例:
licenseModel = 'LICENSE_INCLUDED' && dataStoragePercentage > 40 && lifecycleState != 'FAILED'前述の例では、すべての結果は、licenseModelという名前のフィールドの値としてLICENSE_INCLUDED、dataStoragePercentageという名前のフィールドの値が40より大きい、FAILED以外のlifecycleStateフィールドの値を持ちます。
1つの述語グループをカッコで囲まないかぎり、同じ問合せで2つの異なる論理演算子を結合することはできません。(複数の条件では、同じ論理演算子のみを使用できます。)例:
(licenseModel = 'LICENSE_INCLUDED' && dataStoragePercentage > 40) || lifecycleState != 'FAILED'前述の例では、戻されるすべての結果は、licenseModelという名前のフィールドの値としてLICENSE_INCLUDED、dataStoragePercentageという名前のフィールドの値として40より大きい値、またはlifecycleStateフィールドの値がFAILED以外です。
次のグループも使用できます。
licenseModel = 'LICENSE_INCLUDED' && (dataStoragePercentage > 40 || lifecycleState != 'FAILED')前述の例では、戻されるすべての結果は、licenseModelという名前のフィールドの値としてLICENSE_INCLUDED、dataStoragePercentageという名前のフィールドの値として40より大きい値、またはlifecycleStateという名前のフィールドの値としてFAILED以外の値を持ちます。
licenseModel IN ['LICENSE_INCLUDED', 'BRING_YOUR_OWN_LICENSE'] && dbWorkload IN ['OLTP', 'DW', 'AJD', 'APEX']licenseModelという名前のフィールドの値としてLICENSE_INCLUDEDまたはBRING_YOUR_OWN_LICENSE、dbWorkloadという名前のフィールドの値としてOLTP、DW、AJDまたはAPEXのいずれかになります。前述の例では、次のようなより複雑な問合せ条件に置き換えることができます。(licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'OLTP') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'OLTP') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'DW') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'DW') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'AJD') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'AJD') || (licenseModel = 'LICENSE_INCLUDED' && dbWorkload = 'APEX') || (licenseModel = 'BRING_YOUR_OWN_LICENSE' && dbWorkload = 'APEX')((licenseModel = 'LICENSE_INCLUDED' || licenseModel = 'BRING_YOUR_OWN_LICENSE') && (dbWorkload = 'OLTP' || dbWorkload = 'DW' || dbWorkload = 'AJD' || dbWorkload = 'APEX'))どちらの例でも、論理OR演算子を使用して、論理IN演算子を使用する例よりも、より詳細な用語で同じ条件を効果的に表します。
検索では、曖昧さを減らして意図を明確にするために、左から右の評価は実行されません。
日時値
次のパターン文字列フォーマットのいずれかを使用して、日時値を指定できます。
| 書式設定 | 例 | コメント |
|---|---|---|
<yyyy>-<MM>-<dd> <HH>:<mm>:<ss> <TimeZone>
|
'2018-06-19 16:15:41 PDT', '2018-06-19 16:15:41 -08:00' |
TimeZoneはオプションです。TimeZoneを省略した場合は、UTCが使用されます。
|
<EEE>, <d> <MMM> <yyyy> <HH>:<mm>:<ss> <TimeZone>
|
'Tue, 19 Jun 2018 16:15:41 +0300', '19 June 2018 16:15:41' |
EEEはオプションです。MMMは、MMMMとして表すこともできます。TimeZoneもオプションです。TimeZoneを省略した場合は、UTCが使用されます。 |
<yyyy>-<MM>-<dd>T<HH>:<mm>:<ss>Z
|
'2018-06-19T16:15:41 Z ' |
UTC時間。' |
スペースに注意する必要があります。ダッシュ、コロン、カンマおよび文字'T'と'Z'は文字どおりに解釈されます。前述の表のプレースホルダ値を解釈するには、次のパターン構文を参照してください:
| 文字 | 日付または時刻のコンポーネント | 表示 |
|---|---|---|
y
|
年 |
年 |
M
|
月 |
月 |
d
|
日付(月) |
日付 |
H
|
時(00から23) | 数字 |
m
|
分 | 数字 |
s
|
秒 | 数字 |
E
|
曜日 | テキスト |
繰返しパターン文字は、正確な表示を示します。たとえば、'HH'は、午前0時を表すために'0'ではなく'00'を使用する必要があります。同様に、'EEE'は'Tue'を意味し、'Tuesday'は意味しません。同様に、'MM'は、9月を表すために'9'ではなく'09'を使用する必要があります。
TimeZoneはオプションですが、選択したフォーマットで、次のいずれかの方法でTimeZoneを指定できます:
- 名前。タイム・ゾーンは、GMTやPDTなどの名前で指定できます。値は大文字小文字が区別されません。
- GMTオフセット値。タイム・ゾーンは、GMTオフセットに従って指定できます。たとえば、GMT-08:00です。値は大文字小文字が区別されません。
- ISO 8601タイム・ゾーン。ISO 8601標準に従って、タイム・ゾーンを指定できます。たとえば、-08、-0800または-08:00です。
前述の形式のいずれかを使用するかわりに、日時の値を定数nowとして指定することもできます。定数nowは、現在の時間を分単位の秒レベルの粒度まで表します。
最後に、時間間隔を任意の日時値に対して追加または引くことができます。たとえば、特定の時間で5分以内に作成されたリソースを問い合せることができます。検索では、次の時間間隔をサポートしています。
| 文字 | 日付または時刻のコンポーネント |
|---|---|
s
|
秒 |
m
|
分 |
h
|
時 |
d
|
日 |
w
|
週 |
日時値に関連する時間間隔を指定するには、次のいずれかの書式を使用します。
- now - 3h
- 2018-06-19 16:15:41 PDT + 1h
照合
照合を目的として、conditionsを含むwhere句のかわりに、またはその使用に加えて、matching句を使用できます。matching句によって、conditions(フィールド名、操作および値を含む)を指定する必要がなくなります。matching句は、指定のテキストとともに=(等号)演算子を適用して、すべての索引付きのフィールドを効果的に問い合せます。ただし、完全一致を必要とせずにこれを実行します。たとえば、次の問合せは、matching句を使用して、フリー・テキスト検索と同じように動作します:
query all resources matching 'instance'この問合せによって、「instance」という単語を含むすべてのリソースおよびリソース属性に一致する結果が生成されます。
matching句は、すべての索引付きフィールドに一致があるかどうかを問い合せますが、句読点を含む特殊文字は無視します。
ソート
リソース問合せの最後の句はsorted by句であり、オプションです。sorted by句は、フィールド名に基づいて検索から返された結果を並べ替え、指定したorderに従って結果をリストします。既定では、並べ替え順序を指定しない場合、結果は常に、作成された日時の降順でソートされます。
sorted by句には、次のように指定できます。
fieldName-検索で結果のソートに使用するフィールド。任意のリソースの任意のフィールドを指定できます。指定したフィールドが含まれないリソースは、指定したフィールドを含むリソースの後にリストされます。order- ascまたはdescを指定できます。昇順リストを指定すると、結果が昇順で表示されます。降順リストを指定すると、結果が降順になります。
複数のリソース・タイプの問合せ
問合せを結合することで、一度に複数のリソース・タイプを問い合せることができます。各問合せには独自の条件句を指定できます。結合する問合せの条件が「where」である場合、同じ「where」条件を共有する複数のリソース・タイプに対する問合せがある場合には、構文が異なります。
複数のリソース・タイプの問合せの基本構文は、次のとおりです。
query <resourceType>, <resourceType> resources例:
query group, user resources前述の問合せの例では、テナンシ内のすべてのグループおよびすべてのユーザーが返されます。
次は、条件を含む複数のリソース・タイプの問合せの構文を示しますが、ここでは条件はすべてのリソース・タイプについて同じです。
query <resourceType>, <resourceType> resources where <conditions>例:
query group, user resources where displayName = 'administrator'前述の問合せの例では、表示名「administrator」のすべてのグループおよび表示名「administrator」のすべてのユーザーがバリエーションとともに返されます。
リソース・タイプに異なる条件を適用する必要がある場合は、結合された問合せ間でカンマ区切りのかわりにunionキーワードを使用する必要があります。次に、いくつかのリソース・タイプに対する問合せの構文を示します。一部のリソース・タイプは条件を共有しますが、一部のリソース・タイプは共有しません。
query <resourceType>, <resourceType> resources where <conditions> union <resourceType> resources例:
query group, user resources where displayName = 'administrator' union compartment resources前の例では、すべてのコンパートメント・リソースとともに表示名「administrator」のすべてのグループと表示名「administrator」のすべてのユーザーがバリエーションと一緒に返されます。
または、例:
query group resources union user resources where displayName = 'administrator' union compartment resources前述の例は、すべてのグループとすべてのコンパートメントを戻します。また、表示名「administrator」のすべてのユーザーがバリエーションとともに戻されます。
オプションで、問合せの最後にsorted by句を追加して、すべての結果を昇順または降順に並べ替えることができます。