Auth0 User Search の Lucene クエリ構文と例

Auth0 User Search バージョン 3 向けの Lucene クエリ構文の詳細と例を紹介します。

ユーザーを一覧表示する際は、Lucene クエリ構文の検索クエリを使用して結果を絞り込めます。

正式なリファレンスはLucene クエリ構文リファレンスですが、概略としては、クエリ文字列は一連のタームとブール演算子として解析されます。

​

ターム

ターム は、検索対象の文字列を定義します。タームでは、フィールド、ワイルドカード、範囲を指定できます。

​

フィールド

フィールドは、指定した文字列をどこで検索するかを定義します。ユーザープロファイル属性の一覧で、検索可能なフィールドを確認できます。

• 正規化されたユーザープロファイルフィールド (email、name、given_name、family_name、nickname) の検索値では大文字と小文字が区別されません。これ以外のすべての検索値では、大文字と小文字が区別されます。

• boolean、integer、double、text、object、またはarrayのデータ型を持つapp_metadataおよびuser_metadataフィールドを検索できます。

• 空のarray、空のobject、またはnull値を含むメタデータフィールドは、それらの値がインデックス化されないため検索できません。

• フィールド名を指定しないタームは、user_metadataに一致しません。

検索条件	クエリの例
名前が完全に”eugenio”であるユーザー	name:"eugenio"
メールドメインがexample.comであるユーザー	email.domain:"example.com"
特定の接続を使用するユーザー	identities.connection:"google-oauth2"

メタデータを検索する際は、フィールドへのパスを使用してネストされた値を検索できます。フィールドがarray内にネストされている場合は、arrayの階層を無視できます。たとえば、次のuser_metadata構造の場合:

{
  "full_name": "Example Name",
  "display": {
    "preferredLanguage": "en",
    "fontSize": 13
  },
  "addresses":{
    "cities": [ "Paris", "Seattle" ]
  }
}

検索条件	クエリ例
氏名が “Example Name” であるユーザー	user_metadata.full_name:"Example Name"
優先言語を設定しているユーザー	q: _exists_:user_metadata.display.preferredLanguage
フォントサイズが13に設定されているユーザー	q: user_metadata.display.fontSize:13
都市にParisが含まれるユーザー	q: user_metadata.addresses.cities:"Paris"

​

ワイルドカード

ワイルドカードでは、* 構文を使用して複数の文字を検索できます。

• 接尾辞一致では、リテラルは3文字以上である必要があります。たとえば、name:*abc は使用できますが、name:*ab は使用できません。

• user_metadata はワイルドカードで検索できません。

検索条件	クエリの例
名前に「example」を含むユーザー	name:*example*
メールアドレスが「test」で始まるユーザー	email:test*

​

範囲

範囲では、指定した下限値から上限値までの範囲にある値を検索できます。

• user_metadata を範囲検索することはできません。

検索条件	クエリの例
ログイン回数が9回以下のユーザー	logins_count:[* TO 10}
ログイン回数が10回から99回のユーザー	logins_count:[10 TO 100}
ログイン回数が100回以上のユーザー	logins_count:[100 TO *]
2025年より前に最後にログインしたユーザー	last_login:[* TO 2024-12-31]
最終ログインが2025年12月のユーザー	last_login:[2025-12-01 TO 2025-12-31]

​

ブール演算子

ブール演算子は、タームを論理的に組み合わせるために使用します。ブール演算子は、すべての正規化されたユーザープロファイルのフィールドとルートメタデータのフィールドで使用できます。

検索条件	クエリ例
名前が「example name」または「test user」と完全に一致するユーザー	name:("example name" OR "test user")
検証済みのメールアドレスを持たないユーザー	NOT _exists_:email_verified OR email_verified:false
一度もログインしたことがないユーザー	NOT _exists_:logins_count OR logins_count:0