--- title: SCIM 2.0 searches description: To prevent exhausting server resources, we recommend capping the total number of resources that are matched by a search. The configuration for each SCIM 2.0 resource type contains a lookthrough-limit property that defines this limit (the default lookthrough-limit value is 500). component: pingdirectory version: 10.1 page_id: pingdirectory:pingdirectory_server_administration_guide:pd_ds_scim2_searches canonical_url: https://docs.pingidentity.com/pingdirectory/10.1/pingdirectory_server_administration_guide/pd_ds_scim2_searches.html revdate: September 13, 2023 section_ids: scim-srch: Using paged SCIM searches about-this-task: About this task steps: Steps --- # SCIM 2.0 searches To prevent exhausting server resources, we recommend capping the total number of resources that are matched by a search. The configuration for each SCIM 2.0 resource type contains a `lookthrough-limit` property that defines this limit (the default `lookthrough-limit` value is 500). If a search request exceeds the lookthrough limit, the client receives a 400 response with an error message similar to the following: ``` { "detail": "The search request matched too many results", "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "scimType": "tooMany", "status": "400" } ``` To prevent this error, you have these options: * The client must refine its search filter to return fewer matches. * Configure paged searches as explained in [Using paged SCIM searches](#scim-srch) ## Using paged SCIM searches When searching large data sets, the results can be numerous and produce errors about a request matching too many results relative to the lookthrough limit. Paged searches avoid these errors and also reduce memory utilization. ### About this task The PingDirectory server does SCIM searches using LDAP requests. After you complete the steps below, PingDirectory creates LDAP requests that include request controls to sort and page the search results before returning the results. If your SCIM searches result in an error because the request matched too many results, as discussed in [SCIM 2.0 searches](pd_ds_scim2_searches.html), you can avoid the error by using paged searches. Complete the following steps for each search. ### Steps 1. Decide your SCIM search. | | | | - | -------------------------------------------------------------------------------------------------------------- | | | To get paged results, your search must include at least one of these parameters: startIndex, count, or sortBy. | For example, your search might look like the following search. ``` https://:/scim/v2/Users/?filter=st eq "TX"&sortBy=sn&sortOrder=ascending ``` Here is the corresponding encoded version. ``` https://:/scim/v2/Users/?filter=st%20eq%20%22TX%22&sortBy=sn&sortOrder=ascending ``` On your PingDirectory server, collect some information to use later. Find the SCIM resource type, `structural-ldap-objectclass`, `include-base-dn`, and `include-filter` values by running this command. ```shell $ dsconfig get-scim-resource-type-prop --type-name \ --property structural-ldap-objectclass \ --property include-base-dn \ --property include-filter ``` 2. On the PingDirectory server, complete the following steps. 1. Create a Virtual List View (VLV) index for your search. Each SCIM search that you want to produce paged results must have its own VLV index. Create this index using `dsconfig create-local-db-vlv-index` with the following options. | Option | Description | | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--index-name` | Names the index. | | `--backend-name` | Specifies the name of the local database backend in which to place the index.The default database backend for PingDirectory is userRoot. | | `--set base-dn` | Specifies the desired base dn. This value must match the value of the `include-base-dn` property that you found in the previous step. | | `--set scope` | Is always `whole-subtree`. | | `--set filter` | Specifies the filter.Specify`"(objectclass=)"`where `` is the name of the objectclass used by the SCIM resource type, which you found in the previous step.If the SCIM resource type has the `include-filter` property set, also specify that property value in the filter. For example, if the filter for the objectclass is `(objectclass=inetorgperson)` and the `include-filter` value is `(st=CA)`, specify the `--set filter` argument as `"(&(objectclass=inetorgperson)(st=CA))"`.Specify the LDAP attributes for all the components of your SCIM search filter.For example, if a mapping SCIM resource type maps the LDAP attribute `st` to the SCIM attribute `address.region` and the SCIM search filter requires that `address.region eq TX`, then this filter must include `(st = TX)` instead of `(address.region = TX)`. | | `--set sort-order` | Specifies whether to sort ascending (+) or descending (-) and the LDAP attribute to sort by.If the SCIM search does not specify the `sortBy` parameter, specify the sort order as `+entryUUID`. | Recall the original, decoded SCIM search, shown here. ``` https://:/scim/v2/Users/?filter=st eq "TX"&sortBy=sn&sortOrder=ascending ``` For example, to create a VLV index for that search, run the following command. \+ ```shell $ dsconfig create-local-db-vlv-index --index-name sn \ --backend-name userRoot --set base-dn:ou=people,dc=example,dc=com \ --set scope:whole-subtree \ --set filter:"(&(objectclass=inetorgperson)(st=TX))" --set sort-order:+sn ``` 1. Stop the server. Rebuild the index. Start the server. Run the `rebuild-index` command specifying the baseDN and the name of the index. ``` $ rebuild-index --baseDN --index ``` For example, run these commands. ``` $ stop-server $ rebuild-index --baseDN dc=example,dc=com --index vlv.sn $ start-server ``` 3. Run your SCIM search filter. | | | | - | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | | The search can include only the filter you specified with `--set filter` in the earlier step without the `"(objectclass=)"` portion. | In addition to the Virtual List View request control, the PingDirectory server adds a Server Side request control to the LDAP request. These request controls require certain parameters be set. To satisfy this requirement, the server uses the following parameters. If the client does not provide values for one of the parameters, the search uses the corresponding default value shown in the following table. | Parameter | Default | | ---------- | ------------------------------------------------------------------------------------------------------------ | | startIndex | 1 | | count | The value of the `lookthrough-limit` property of the SCIM resource type being searched. That default is 500. | | sortBy | entryUUIDWith this default, the results appear unsorted. | | sortOrder | ascending |