From f9de0103791eb76b4ae61c9f147cae61d95c3277 Mon Sep 17 00:00:00 2001 From: Arne Luenser Date: Wed, 17 Jun 2026 17:45:01 +0200 Subject: [PATCH] feat: update search API --- .../curl/search/advanced-result.json | 102 +++++++++--------- code-examples/curl/search/advanced.sh | 2 +- code-examples/curl/search/model.jsonc | 5 +- .../search/identity-search-api.mdx | 33 +++--- .../search/identity-search-console.mdx | 4 +- 5 files changed, 74 insertions(+), 72 deletions(-) diff --git a/code-examples/curl/search/advanced-result.json b/code-examples/curl/search/advanced-result.json index bd67fb09e..7a3dbc77e 100644 --- a/code-examples/curl/search/advanced-result.json +++ b/code-examples/curl/search/advanced-result.json @@ -3,14 +3,14 @@ { "counts": [ { - "count": 534, - "highlighted": "6e0b1f71-4236-44a3-a730-a033fcd21eab", - "value": "6e0b1f71-4236-44a3-a730-a033fcd21eab" + "count": 24, + "highlighted": "68efa2e9-fcd5-4104-8f49-7c51fa5752e2", + "value": "68efa2e9-fcd5-4104-8f49-7c51fa5752e2" }, { - "count": 489, - "highlighted": "6bd7de58-a3d4-412c-a3fd-0c04a14b03f7", - "value": "6bd7de58-a3d4-412c-a3fd-0c04a14b03f7" + "count": 20, + "highlighted": "d936269a-2b49-4077-b4c8-2a256979fd27", + "value": "d936269a-2b49-4077-b4c8-2a256979fd27" } ], "field_name": "organization_id", @@ -21,25 +21,26 @@ } } ], - "found": 2163, + "found": 56, "hits": [ { "document": { "available_aal": "aal0", - "created_at": 1769995344, - "id": "8a2a14af-7a89-4424-aebd-1db3e3b8a229", - "nid": "e70f3b9e-f343-40e6-89f1-de24e459722e", - "organization_id": "6bd7de58-a3d4-412c-a3fd-0c04a14b03f7", + "created_at": 1781570773, + "id": "f329a237-3725-495f-ad5b-ceb28bb77609", + "nid": "8180c44b-2f36-4790-b22e-713cb3b60425", + "organization_id": "d936269a-2b49-4077-b4c8-2a256979fd27", + "region": "asia-northeast", "schema_id": "preset://basic", "state": "active", "traits": { - "email": "louise_henderson760@aol.com", + "email": "kimberly.schmidt87@laposte.net", "name": { - "first": "Louise", - "last": "Henderson" + "first": "Kimberly", + "last": "Schmidt" } }, - "updated_at": 1770125357 + "updated_at": 1781710590 }, "highlight": {}, "highlights": [] @@ -47,20 +48,21 @@ { "document": { "available_aal": "aal0", - "created_at": 1769900788, - "id": "dc6b133f-363a-42e2-83b1-78a4a81e0a07", - "nid": "e70f3b9e-f343-40e6-89f1-de24e459722e", - "organization_id": "6bd7de58-a3d4-412c-a3fd-0c04a14b03f7", + "created_at": 1781133323, + "id": "5f549865-b8ac-48a1-a7e2-6cdddf4645e3", + "nid": "8180c44b-2f36-4790-b22e-713cb3b60425", + "organization_id": "68efa2e9-fcd5-4104-8f49-7c51fa5752e2", + "region": "asia-northeast", "schema_id": "preset://basic", "state": "active", "traits": { - "email": "patricia.lefebvre570@mailbox.org", + "email": "wolfgangcampbell137@ymail.com", "name": { - "first": "Patricia", - "last": "Lefebvre" + "first": "Wolfgang", + "last": "Campbell" } }, - "updated_at": 1770125352 + "updated_at": 1781710601 }, "highlight": {}, "highlights": [] @@ -68,20 +70,21 @@ { "document": { "available_aal": "aal0", - "created_at": 1769785191, - "id": "f748b84f-8ad0-4f72-8a3c-5e38bd0fe96d", - "nid": "e70f3b9e-f343-40e6-89f1-de24e459722e", - "organization_id": "6e0b1f71-4236-44a3-a730-a033fcd21eab", + "created_at": 1776824080, + "id": "ec946791-8c24-4848-9916-7a98285cbd3e", + "nid": "8180c44b-2f36-4790-b22e-713cb3b60425", + "organization_id": "68efa2e9-fcd5-4104-8f49-7c51fa5752e2", + "region": "asia-northeast", "schema_id": "preset://basic", "state": "active", "traits": { - "email": "steven.r740@posteo.de", + "email": "alainlopez11@zoho.com", "name": { - "first": "Steven", - "last": "Roussel" + "first": "Alain", + "last": "Lopez" } }, - "updated_at": 1770125356 + "updated_at": 1781710574 }, "highlight": {}, "highlights": [] @@ -89,20 +92,21 @@ { "document": { "available_aal": "aal0", - "created_at": 1769316538, - "id": "1c00a491-c5cf-47d5-a306-2214248f81d5", - "nid": "e70f3b9e-f343-40e6-89f1-de24e459722e", - "organization_id": "6bd7de58-a3d4-412c-a3fd-0c04a14b03f7", + "created_at": 1773833986, + "id": "4f0ce13f-ffff-47b4-a853-b90fe438e6c7", + "nid": "8180c44b-2f36-4790-b22e-713cb3b60425", + "organization_id": "d936269a-2b49-4077-b4c8-2a256979fd27", + "region": "us-west", "schema_id": "preset://basic", "state": "active", "traits": { - "email": "thomasmitchell631@wanadoo.fr", + "email": "jacob.d36@msn.com", "name": { - "first": "Thomas", - "last": "Mitchell" + "first": "Jacob", + "last": "Durand" } }, - "updated_at": 1770125354 + "updated_at": 1781710579 }, "highlight": {}, "highlights": [] @@ -110,26 +114,26 @@ { "document": { "available_aal": "aal0", - "created_at": 1769293967, - "id": "07421d7e-0e84-4e05-bd1e-9c446dc94a6d", - "nid": "e70f3b9e-f343-40e6-89f1-de24e459722e", - "organization_id": "6bd7de58-a3d4-412c-a3fd-0c04a14b03f7", + "created_at": 1773463258, + "id": "4f48a1bc-1f8f-4592-a36a-d9c799ae08da", + "nid": "8180c44b-2f36-4790-b22e-713cb3b60425", + "region": "us-west", "schema_id": "preset://basic", - "state": "inactive", + "state": "active", "traits": { - "email": "vhughes947@zoho.com", + "email": "christophe_patel8@outlook.de", "name": { - "first": "Valerie", - "last": "Hughes" + "first": "Christophe", + "last": "Patel" } }, - "updated_at": 1770125361 + "updated_at": 1781710646 }, "highlight": {}, "highlights": [] } ], - "out_of": 2163, + "out_of": 56, "page": 1, "request_params": { "collection_name": "identities", diff --git a/code-examples/curl/search/advanced.sh b/code-examples/curl/search/advanced.sh index 8524981ee..d1b99c7df 100644 --- a/code-examples/curl/search/advanced.sh +++ b/code-examples/curl/search/advanced.sh @@ -1,5 +1,5 @@ export ORY_API_KEY="ory_pat_XXXXXXXXXXXXXXXX" -export ORY_SLUG="upbeat-lalande-zu8omm6wwp" # replace with your Ory slug +export ORY_SLUG="zealous-perlman-yvt3ifefzf" # replace with your Ory slug # list identities which do not have two-factor authentication enabled, # resolved by the organization to which they belong, diff --git a/code-examples/curl/search/model.jsonc b/code-examples/curl/search/model.jsonc index d04652242..88fa2ea96 100644 --- a/code-examples/curl/search/model.jsonc +++ b/code-examples/curl/search/model.jsonc @@ -1,5 +1,6 @@ { "id": "d52d5bdb-74b4-4aa0-b706-d1e9c853bd81", // the identity ID + "region": "eu-central", // in which Ory Network region the identity's personal data is stored, facet "organization_id": "org-id-123", // optional, facet "external_id": "external-id-123", // optional, indexed "created_at": 1725031437, // UNIX timestamp, facet, sortable @@ -8,10 +9,10 @@ "schema_id": "preset://email", // identity schema ID, facet "available_aal": "aal1", // "aal2" etc, facet "metadata_admin": { - "role": "user" // custom admin metadata, indexed, facet, search via `query_by=metadata_admin.role` + "role": "user" // custom admin metadata, prefix-indexed, search via `query_by=metadata_admin.role` }, "metadata_public": { - "foo": "bar" // custom public metadata, indexed, facet, search via `query_by=metadata_public.foo` + "foo": "bar" // custom public metadata, prefix-indexed, search via `query_by=metadata_public.foo` }, "traits": { "email": "wgiho@agpaa.com" // traits based on identity schema, indexed, search via `query_by=traits.email` diff --git a/docs/kratos/manage-identities/search/identity-search-api.mdx b/docs/kratos/manage-identities/search/identity-search-api.mdx index 459202a2f..1df6c842c 100644 --- a/docs/kratos/manage-identities/search/identity-search-api.mdx +++ b/docs/kratos/manage-identities/search/identity-search-api.mdx @@ -57,26 +57,17 @@ See the following examples for how to configure and use the Typesense SDKs to se ## Data model -The collection `identities-{your-project-id}` contains one document per identity. Each document contains the following fields: +The collection `identities` contains one document per identity. Each document contains the following fields: ```mdx-code-block {model} ``` -:::tip - -To avoid timing out search requests, specify the exact fields you want to search in using the `query_by` parameter. For example, -to search for identities by email, use `query_by=traits.email`. - -::: +:::important -:::note - -Because of technical limitations, non-string data in `metadata_admin` and `metadata_public` will be indexed as strings and -returned from the Search API as strings. - -To retrieve the original JSON data, fetch the full identity using the -[Get Identity API](/reference/api#tag/identity/operation/getIdentity). +This API provides full-text _search_ into identity data, not a database. The index is updated asynchronously and results are +ranked for relevance and discovery. Do not use it to answer correctness-critical questions such as organization membership or +permissions — use the identity management APIs and Ory Permissions for those. ::: @@ -100,8 +91,13 @@ arbitrary search queries. An example: :::tip -Most fields support infix-searching as well, so queries like `query_by=@example.com&infix=always&query_by=traits.email` are -possible. +To avoid timing out search requests, specify the exact fields you want to search in using the `query_by` parameter. For example, +to search for identities by email, use `query_by=traits.email`. + +Most fields support infix-searching as well, so queries like `q=@example.com&infix=always&query_by=traits.email` are possible. + +Be mindful that infix searches are considerably more expensive to run, so to avoid timing out search requests, use them only when +necessary. ::: @@ -118,8 +114,9 @@ will be a delay between creating, updating, or deleting an identity and the chan aim for a delay of less than one second during normal operation, but cannot provide any guarantees. The search index will have to be rebuilt periodically, during which time we cannot service search requests. -We recommend you use the search API for non-time-critical use cases, such as admin UIs or background jobs, where you need to full -capability of full-text search, filtering, faceting, and sorting. +We recommend you use the search API for non-time-critical use cases, such as admin UIs or background jobs, where you need the full +capability of full-text search, filtering, faceting, and sorting. Do not use it to answer correctness-critical questions such as +organization membership or permissions — use the identity management APIs and Ory Permissions for those. Before displaying search results to end-users or otherwise using the search results for business logic, we recommend you always [fetch the full identity](/reference/api#tag/identity/operation/getIdentity) from the main identity store using the identity ID diff --git a/docs/kratos/manage-identities/search/identity-search-console.mdx b/docs/kratos/manage-identities/search/identity-search-console.mdx index abc78a705..f2cf328ff 100644 --- a/docs/kratos/manage-identities/search/identity-search-console.mdx +++ b/docs/kratos/manage-identities/search/identity-search-console.mdx @@ -7,8 +7,8 @@ sidebar_label: Ory Console Search for identities by navigating to . Use the search bar to find identities by email, username, first/last name, or any other custom traits you have defined. Admin and -public metadata is also searchable. Use the State (`Active`/`Inactive`), Identity Schema, and Organization filters to narrow down -your search results. +public metadata are also searchable. Use the Status (`Active`/`Inactive`), Identity Schema, Organization, and Registration date +facets to narrow down your search results. Identity search supports a maximum result set size of 250 identities. If your search query matches more than 250 identities, only the first 250 results will be shown, along with a message about how many identities match your search query in total.