# React Hooks



import NpmLogo from '@site/static/img/npm-logo.png';

<div class="row margin-bottom--md">
  <div class="col">
    <a href="https://www.npmjs.com/package/@dynatrace-sdk/react-hooks" target="_blank" rel="noopener noreferrer"> <span class="margin-right--xs">@dynatrace-sdk/react-hooks</span> <img className="no-zoom" width="20px" src={NpmLogo} /> </a>
  </div>
  <div class="col" style={{textAlign: 'right'}}>
    <a href="https://www.npmjs.com/package/@dynatrace-sdk/react-hooks/v/1.12.1" target="_blank" rel="noopener noreferrer">v1.12.1</a>
  </div>
</div>

```bash
npm install @dynatrace-sdk/react-hooks
```


### Why should I use this package?

This package simplifies interactions with Grail, documents, and app states in React by encapsulating complex state management. It offers easy-to-use hooks that integrate seamlessly with client packages, enhancing developer productivity and usability in React applications.

### Simplified data querying from Grail

Traditionally, querying data in Dynatrace involves using the client-query package and managing complex React state. The `useDql` hook in this package streamlines this process. The following example showcases how to fetch data with a DQL query:

```javascript
const { data, error, isLoading } = useDql('fetch logs');
```

This hook is fully compatible with the parameters used in the `queryExecute` function of the `@dynatrace-sdk/client-query` package.

For instance, to limit the number of results returned:

```javascript
const { data, error, isLoading, refetch } = useDql(
  {
    query: 'fetch logs',
    maxResultRecords: 2000,
  }
);
```

You can delay the execution of the query until a user clicks on a button by passing additional query options to the hook:

```javascript
const { data, error, isLoading, refetch } = useDql('fetch logs', { enabled: false });

function onClickQuery() {
  refetch();
}
```

You should add appropriate scopes to your app's configuration based on the query type. For more details, refer to the [Bucket and table permissions in Grail documentation](https://www.dynatrace.com/support/help/platform/grail/assign-permissions-in-grail).

### Interacting with documents and app states

Beyond DQL queries, our hooks facilitate interactions with documents and app state. They allow control over immediate or deferred query execution.

```javascript
const { data, error, isLoading } = useDocument({ id: documentId }, { autoFetch: true });
```

For creating, updating, or deleting documents or app state, an explicit execute call is necessary:

```javascript
const { data, execute, error } = useCreateDocument();

function onClickCreateDocument() {
  execute(DOCUMENT_DATA);
}
```

Depending on your interaction type, add these scopes to your app configuration:

| Function | Scope |
| ----- | ----- |
| Document read | document:documents:read |
| Document write/update | document:documents:write |
| Document delete | document:documents:delete |
| State read | state:app-states:read |
| State write | state:app-states:write |
| State delete | state:app-states:delete |
| User state read | state:user-app-states:read |
| User state write | state:user-app-states:write |
| User state delete | state:user-app-states:delete |

### Simplified Use of Davis® Analyzers

Leveraging Davis® analyzers traditionally involves complex state management and polling logic, alongside the `@dynatrace-sdk/client-davis-analyzers` package. The `useAnalyzer` hook in this package makes this process much more straightforward:

```javascript
const { data, error, isLoading } = useAnalyzer({
  analyzerName: 'dt.statistics.GenericForecastAnalyzer',
  body: {
    timeSeriesData: {
      expression: query,
    },
  },
});
```

This hook supports all the parameters available in the executeAnalyzer method from the `@dynatrace-sdk/client-davis-analyzers` package.

To defer the execution of the analyzer until a user action, like a button click, configure the hook with additional options:

```javascript
const { data, error, isLoading, refetch } = useAnalyzer({
  analyzerName: 'dt.statistics.GenericForecastAnalyzer',
  body: {
    timeSeriesData: {
      expression: query,
    },
  }, 
  {
    autoFetch: false,
    autoFetchOnUpdate: true,
  }
});

function onExecuteAnalyzer() {
  refetch();
}
```
In your app's configuration, include the necessary scope:

| Function | Scope |
| ----- | ----- |
| Use analyzer | davis:analyzers:execute |

### App functions

The useAppFunction hook is the simplest way to call app functions. As the other hooks in this package, it provides state handling for loading and error states:

```javascript
const { data, error, isLoading } = useAppFunction({ name: 'functionName', data: 'data' });
```

Sometimes you want to delay the execution of the app function until a user clicks on a button. This can be achieved by passing additional options to the hook:

```javascript
const { data, error, isLoading, refetch } = useAppFunction({ name: 'functionName', data: 'data' }, { autoFetch: false, autoFetchOnUpdate: false });

function onClick() {
  refetch();
}
```


## Hooks



### useAccessorPermissionsV2

<div class="padding-bottom--md">
<strong>useAccessorPermissionsV2(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Load accessor permissions.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|AccessorPermissionsParamsV2|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useAllUsersPermissionsV2

<div class="padding-bottom--md">
<strong>useAllUsersPermissionsV2(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Load all-users permissions.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|LoadAllUsersPermissionsParamsV2|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useAnalyzer

<div class="padding-bottom--md">
<strong>useAnalyzer(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Execute an analyzer with the given data.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|AnalyzerParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useAppFunction

<div class="padding-bottom--md">
<strong>useAppFunction(params,options?): \{ cancel, data, error, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Call specified app function by name.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|AppFunctionParams|App function params. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useAppState

<div class="padding-bottom--md">
<strong>useAppState(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Gets app state



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|AppStateParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useAppStates

<div class="padding-bottom--md">
<strong>useAppStates(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

List app states



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|AppStatesParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useCreateDocument

<div class="padding-bottom--md">
<strong>useCreateDocument(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Create a new document.



</div>







</div>





### useCreatePermissionsV2

<div class="padding-bottom--md">
<strong>useCreatePermissionsV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Create a new permissions.



</div>







</div>





### ~~useCreateSettings~~

> ⚠️ **Deprecated**
> Use V2 instead.

<div class="padding-bottom--md">
<strong>useCreateSettings(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Create a new setting.



</div>







</div>





### useCreateSettingsV2

<div class="padding-bottom--md">
<strong>useCreateSettingsV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Create a new setting.



</div>







</div>





### useDeleteAccessorPermissionsV2

<div class="padding-bottom--md">
<strong>useDeleteAccessorPermissionsV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Delete the accessor permissions



</div>







</div>





### useDeleteAllUsersPermissionsV2

<div class="padding-bottom--md">
<strong>useDeleteAllUsersPermissionsV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Delete the all-users permissions



</div>







</div>





### useDeleteAppState

<div class="padding-bottom--md">
<strong>useDeleteAppState(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Deletes app state



</div>







</div>





### useDeleteAppStates

<div class="padding-bottom--md">
<strong>useDeleteAppStates(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Delete all app states



</div>







</div>





### useDeleteDocument

<div class="padding-bottom--md">
<strong>useDeleteDocument(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Delete the document



</div>







</div>





### ~~useDeleteSettings~~

> ⚠️ **Deprecated**
> Use V2 instead.

<div class="padding-bottom--md">
<strong>useDeleteSettings(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Delete the setting



</div>







</div>





### useDeleteSettingsV2

<div class="padding-bottom--md">
<strong>useDeleteSettingsV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Delete the setting



</div>







</div>





### useDeleteUserAppState

<div class="padding-bottom--md">
<strong>useDeleteUserAppState(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Delete user app state



</div>







</div>





### useDeleteUserAppStates

<div class="padding-bottom--md">
<strong>useDeleteUserAppStates(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Delete all user app states



</div>







</div>





### useDocument

<div class="padding-bottom--md">
<strong>useDocument(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Retrieve metadata and content for documents.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|DocumentParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useDocumentMetaData

<div class="padding-bottom--md">
<strong>useDocumentMetaData(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Retrieve document metadata.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|DocumentMetaDataParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useDownloadDocument

<div class="padding-bottom--md">
<strong>useDownloadDocument(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Download document content



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|DownloadDocumentParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useDql

<div class="padding-bottom--md">
<strong>useDql(query,options?): [UseDqlResult](#usedqlresult)&lt;T&gt;</strong>

<div class="padding-left--md">

React hook for executing DQL (Dynatrace Query Language) queries against Grail.

Use this hook to run DQL queries in React components and manage query state with less boilerplate.
It returns query data, loading and error state, and functions to cancel or rerun the query.

- By default, queries that are in-flight are **cancelled when the browser tab
  loses focus**. Set `runInBackground: true` to keep them running.
- Results are cached for 60 seconds by default (`staleTime`). Calling `refetch`
  while data is still fresh returns the cached result; use `forceRefetch` to
  bypass the cache.
- The hook automatically retries on HTTP 429 (Too Many Requests) responses
  using the `retryAfterSeconds` header when available, falling back to exponential
  back-off.
- When `enablePreview` is set on the query params, intermediate partial results
  are exposed via `data` while the query is still running.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|query<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String) &#124; [DqlQueryParams](#dqlqueryparams)|<p>A DQL query string, or a <a href="#dqlqueryparams" target="_blank" rel="noopener noreferrer" >DqlQueryParams</a> object for full control over execution parameters (timezone, timeframe, locale, etc.). Parameters provided here are merged with any values from a parent <a href="#dqlqueryparamsprovider" target="_blank" rel="noopener noreferrer" >DqlQueryParamsProvider</a>, with per-call values taking precedence.</p>  |
|options|[UseDqlOptions](#usedqloptions)&lt;T&gt;|Optional configuration for the hook behavior. |




#### Returns

| Return type | Description |
|---|---|
|[UseDqlResult](#usedqlresult) | Returns the query result, loading and error state, progress information, and functions to cancel or rerun the query.|



<details>
<summary>
Basic usage

</summary>

```tsx
function HostList() {
  const { data, isLoading, error } = useDql(
    'fetch dt.entity.host | fields entity.name, state'
  );

  if (isLoading) return <span>Loading...</span>;
  if (error) return <span>Error: {error.message}</span>;

  return (
    <ul>
      {data?.records.map((host) => (
        <li key={host['entity.name']}>{host['entity.name']}</li>
      ))}
    </ul>
  );
}
```

</details>

<details>
<summary>
Typed records

</summary>

```tsx
interface MyRecord {
  state: string;
}

const { data } = useDql<MyRecord>(
  'fetch dt.entity.host | fields state'
);
// data?.records is typed as MyRecord[]
```

</details>

<details>
<summary>
Advanced query parameters

</summary>

```tsx
const result = useDql({
  query: 'fetch logs | sort timestamp desc | limit 100',
  defaultTimeframeStart: 'now()-2h',
  defaultTimeframeEnd: 'now()',
  timezone: 'Europe/Berlin',
  locale: 'en_US',
  enablePreview: true,
});
```

</details>

<details>
<summary>
Shared query parameters via context

</summary>

```tsx
<DqlQueryParamsProvider
  defaultTimeframeStart="now()-1h"
  defaultTimeframeEnd="now()"
>
  <HostList />
  <LogViewer />
</DqlQueryParamsProvider>
```

</details>

<details>
<summary>
Cancellation and refetching

</summary>

```tsx
const { cancel, refetch, forceRefetch } = useDql('fetch logs');

// Cancel the in-flight query
await cancel();

// Refetch only if data is stale
await refetch();

// Force a fresh fetch regardless of stale time
await forceRefetch();
```

</details>

<details>
<summary>
Tracking progress

</summary>

```tsx
const { data, state, progress } = useDql('fetch logs | summarize count()');

if (state === 'RUNNING') {
  return <ProgressBar value={progress} />;
}
```

</details>



</div>





### ~~useDqlQuery~~

> ⚠️ **Deprecated**
> Use `useDql` hook instead.

<div class="padding-bottom--md">
<strong>useDqlQuery(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Use this hook to execute a DQL query.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|~~params~~<sup>**DEPRECATED**</sup><sup>*required</sup>|QueryParams|Query and enrich options that will be executed. |
|~~options~~<sup>**DEPRECATED**</sup>|HookOptions|Additional options for the react hook. |




#### Returns

| Description |
|---|
|The state of the query, including the result and functions to refetch or cancel the query.|





</div>





### ~~useEffectivePermissions~~

> ⚠️ **Deprecated**
> Use V2 instead.

<div class="padding-bottom--md">
<strong>useEffectivePermissions(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Retrieve effective settings permissions for the calling user.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|~~params~~<sup>**DEPRECATED**</sup><sup>*required</sup>|Omit&lt;\{ abortSignal, body \} &#124; "abortSignal"&gt;|Parameters for the client sdk call. |
|~~options~~<sup>**DEPRECATED**</sup>|HookOptions|Additional options for the react hook. |








</div>





### useEffectivePermissionsV2

<div class="padding-bottom--md">
<strong>useEffectivePermissionsV2(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Retrieve effective settings permissions for the calling user.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|Omit&lt;\{ abortSignal, body \} &#124; "abortSignal"&gt;|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useGrailFields

<div class="padding-bottom--md">
<strong>useGrailFields(options): [UseGrailFieldsResult](#usegrailfieldsresult)&lt;TData&gt;</strong>

<div class="padding-left--md">

Fetches Grail fields from both autocomplete and DSS query sources
and exposes standard React Query status flags.



</div>


#### Parameters

| Name | Type |
| --- | --- |
|options<sup>*required</sup>|[UseGrailFieldsOptions](#usegrailfieldsoptions)&lt;TData&gt;| 




#### Returns

| Return type | Description |
|---|---|
|[UseGrailFieldsResult](#usegrailfieldsresult) | <p>The raw query data (or the value returned by <code>select</code>), plus React Query state flags (<code>isLoading</code>, <code>isError</code>, <code>isSuccess</code>, <code>errors</code>, <code>refetch</code>, <code>cancel</code>).</p> |



<details>
<summary>
Basic usage:

</summary>

```tsx
const { data, isLoading } = useGrailFields({
  autocompleteQueryOptions: { query: 'fetch logs' },
  dssQueryOptions: { dataObject: 'logs' },
});
// data.autocompleteData, data.dssData
```

</details>

<details>
<summary>
With select transform:

</summary>

```tsx
const { data } = useGrailFields({
  autocompleteQueryOptions: { query: 'fetch logs' },
  dssQueryOptions: { dataObject: 'logs' },
  select: ({ autocompleteData }) =>
    autocompleteData?.suggestions?.map((s) => s.suggestion ?? '') ?? [],
});
```

</details>



</div>





### useListDocuments

<div class="padding-bottom--md">
<strong>useListDocuments(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

List all documents accessible to you.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|undefined &#124; ListDocumentsParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### usePermissionsV2

<div class="padding-bottom--md">
<strong>usePermissionsV2(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Load permissions.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|PermissionsParamsV2|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useSetAppState

<div class="padding-bottom--md">
<strong>useSetAppState(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Updates app state



</div>







</div>





### useSetUserAppState

<div class="padding-bottom--md">
<strong>useSetUserAppState(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Updates user app state



</div>







</div>





### ~~useSettings~~

> ⚠️ **Deprecated**
> Use V2 instead.

<div class="padding-bottom--md">
<strong>useSettings(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Retrieve metadata and content for settings.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|~~params~~<sup>**DEPRECATED**</sup><sup>*required</sup>|SettingsParams|Parameters for the client sdk call. |
|~~options~~<sup>**DEPRECATED**</sup>|HookOptions|Additional options for the react hook. |








</div>





### ~~useSettingsObjects~~

> ⚠️ **Deprecated**
> Use V2 instead.

<div class="padding-bottom--md">
<strong>useSettingsObjects(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Retrieve metadata and content for settings.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|~~params~~<sup>**DEPRECATED**</sup><sup>*required</sup>|SettingsObjectParams|Parameters for the client sdk call. |
|~~options~~<sup>**DEPRECATED**</sup>|HookOptions|Additional options for the react hook. |








</div>





### useSettingsObjectsV2

<div class="padding-bottom--md">
<strong>useSettingsObjectsV2(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Retrieve metadata and content for settings.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|SettingsObjectParamsV2|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useSettingsV2

<div class="padding-bottom--md">
<strong>useSettingsV2(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Retrieve metadata and content for settings.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|SettingsParamsV2|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useTransferOwnershipV2

<div class="padding-bottom--md">
<strong>useTransferOwnershipV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Transfer ownership.



</div>







</div>





### useUpdateAccessorPermissionsV2

<div class="padding-bottom--md">
<strong>useUpdateAccessorPermissionsV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Update accessor permissions.



</div>







</div>





### useUpdateAllUsersPermissionsV2

<div class="padding-bottom--md">
<strong>useUpdateAllUsersPermissionsV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Update all-users permissions.



</div>







</div>





### useUpdateDocument

<div class="padding-bottom--md">
<strong>useUpdateDocument(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Update metadata and content.



</div>







</div>





### useUpdateDocumentMetadata

<div class="padding-bottom--md">
<strong>useUpdateDocumentMetadata(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Update document metadata



</div>







</div>





### ~~useUpdateSettings~~

> ⚠️ **Deprecated**
> Use V2 instead.

<div class="padding-bottom--md">
<strong>useUpdateSettings(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Update metadata and content.



</div>







</div>





### useUpdateSettingsV2

<div class="padding-bottom--md">
<strong>useUpdateSettingsV2(): \{ data, error, errorDetails, execute, isError, isLoading, isSuccess, status \}</strong>

<div class="padding-left--md">

Update metadata and content.



</div>







</div>





### useUser

<div class="padding-bottom--md">
<strong>useUser(uuid,options): UseUserResult</strong>

<div class="padding-left--md">

React hook for fetching a single user by UUID.

Internally batches multiple concurrent `useUser` calls into a single bulk
POST request to the IAM API, deduplicating UUIDs and chunking into batches
of ≤100 to avoid silent truncation.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|uuid<sup>*required</sup>|undefined &#124; [string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The user UUID to fetch, or <code>undefined</code> to disable the query. |
|options<sup>*required</sup>|[UseUserOptions](#useuseroptions)|Additional options for the hook. |




#### Returns

| Description |
|---|
|The user data, loading state, and error information.|



<details>
<summary>
Code example
</summary>

```ts
const { data: user, isLoading, error } = useUser('user-uuid-123');
```

</details>



</div>





### useUserAppState

<div class="padding-bottom--md">
<strong>useUserAppState(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

Get user app state



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|UserAppStateParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useUserAppStates

<div class="padding-bottom--md">
<strong>useUserAppStates(params,options?): \{ cancel, data, error, errorDetails, isError, isLoading, isSuccess, refetch, status \}</strong>

<div class="padding-left--md">

List user app states



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|params<sup>*required</sup>|UserAppStatesParams|Parameters for the client sdk call. |
|options|HookOptions|Additional options for the react hook. |








</div>





### useUsers

<div class="padding-bottom--md">
<strong>useUsers(uuids,options): [UseUsersResult](#useusersresult)</strong>

<div class="padding-left--md">

React hook for fetching multiple users by their UUIDs.

Internally batches all UUID lookups into chunked bulk POST requests
to the IAM API (≤100 UUIDs per chunk), with per-UUID caching.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|uuids<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;|Array of user UUIDs to fetch. |
|options<sup>*required</sup>|[UseUserOptions](#useuseroptions)|Additional options for the hook. |




#### Returns

| Description |
|---|
|Aggregated result with a Map of UUID→user data and loading states.|



<details>
<summary>
Code example
</summary>

```ts
const { data, users, isLoading } = useUsers(['uuid-1', 'uuid-2', 'uuid-3']);
```

</details>



</div>



## Components



### DqlQueryParamsProvider

<div class="padding-bottom--md">


<div class="padding-left--md">

Provider component for Dql query params context to use with the `useDql` hook.



</div>


#### Parameters

| Name | Type |
| --- | --- |
|props<sup>*required</sup>|[DqlQueryParamsContextProps](#dqlqueryparamscontextprops)| 








</div>



## Functions



### UseUsersProvider

<div class="padding-bottom--md">
<strong>UseUsersProvider(props): ReactElement&lt;[any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any) &#124; [string](https://developer.mozilla.org/en-US/docs/Glossary/String) &#124; JSXElementConstructor&lt;[any](https://www.typescriptlang.org/docs/handbook/2/everyday-types.html#any)&gt;&gt;</strong>

<div class="padding-left--md">

Provider component for configuring the `useUser` and `useUsers` hooks.



</div>


#### Parameters

| Name | Type |
| --- | --- |
|props<sup>*required</sup>|[UseUsersConfig](#useusersconfig)| 






<details>
<summary>
Code example
</summary>

```ts
<UseUsersProvider levelType="account" levelId="abc-123">
  <MyTable />
</UseUsersProvider>
```

</details>



</div>





### getGrailFieldsQueryOptions

<div class="padding-bottom--md">
<strong>getGrailFieldsQueryOptions(autocompleteOptions,dssOptions): [GrailFieldsQueryOptions](#grailfieldsqueryoptions)</strong>

<div class="padding-left--md">

Creates combined query options for both autocomplete and DSS queries used in [useGrailFields](#usegrailfields).
This allows consumers to prefetch both queries in parallel.



</div>


#### Parameters

| Name | Type | Description |
| --- | --- | --- |
|autocompleteOptions<sup>*required</sup>|[AutocompleteQueryOptions](#autocompletequeryoptions)|Options for the autocomplete query. |
|dssOptions<sup>*required</sup>|[DssQueryOptions](#dssqueryoptions)|Options for the DSS query. |




#### Returns

| Description |
|---|
|An object containing query options for both autocomplete and DSS queries.|



<details>
<summary>
Code example
</summary>

```tsx
const queryClient = useQueryClient();
const { autocomplete, dss } = getGrailFieldsQueryOptions(
  { query: 'fetch logs' },
  { dataObject: 'logs' },
);
await Promise.all([
  queryClient.prefetchQuery(autocomplete),
  queryClient.prefetchQuery(dss),
]);
```

</details>



</div>



## Constants

### DqlQueryParamsContext
<div class="padding-left--md">

Context storing Dql query params.

</div>

<div class="padding-left--md">
Context&lt;[DqlQueryParamsContextProps](#dqlqueryparamscontextprops)&gt;

</div>

## Types

### AnalyzerHookOptions



#### Properties

| Name | Type | Description |
| --- | --- | --- |
|~~autoFetch~~<sup>**DEPRECATED**</sup><sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|If set to true, the hook will execute the query immediately. If set to false, the query only executes when calling refetch. |
|~~autoFetchOnUpdate~~<sup>**DEPRECATED**</sup><sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|If set to true, the hook will execute the query on a component update. If set to false, it is not executed on update. |
|~~onError~~<sup>**DEPRECATED**</sup>|(error: Error) => void| |


### AutocompleteQueryOptions
Options for the autocomplete query passed to [useGrailFields](#usegrailfields).


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|enabled|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Whether the query is enabled. |
|query<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The DQL query string used to derive autocomplete field suggestions. |
|retry|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number) &#124; [boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Number of retries or boolean to indicate whether to retry on failure. |
|staleTime|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Time in milliseconds before the query is considered stale. |


### DqlQueryParams
Parameters for query execution.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|defaultSamplingRatio|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Default sampling ratio. By default no sampling is applied. No upper limit but will be normalized to a power of 10 less than or equal to 100000. |
|defaultScanLimitGbytes|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Default scan limit. Can be overridden in DQL. Default value is configured on application level (see documentation of FETCH command). No upper limit. Use -1 for no limit. |
|defaultTimeframeEnd|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The query timeframe 'end' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'start' parameter is missing, the whole timeframe is ignored. <em>Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.</em> |
|defaultTimeframeStart|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The query timeframe 'start' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'end' parameter is missing, the whole timeframe is ignored. <em>Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.</em> |
|dtClientContext|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The dt-client-context header is an optional string parameter used for monitoring purposes. When included in a request, it helps retrieve information about the execution of the query. It shouldn't hold sensitive information. |
|enablePreview|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Request preview results. If a preview is available within the requestTimeoutMilliseconds, then it will be returned as part of the response. |
|enforceQueryConsumptionLimit|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|(DEPRECATED use body parameter 'enforceQueryConsumptionLimit' instead) If set, query consumption limit will be enforced. |
|enrich|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|If set additional data will be available in the metadata section. |
|fetchTimeoutSeconds|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The time limit for fetching data. Soft limit as further data processing can happen. No upper limit in API but application level default and maximum fetch timeout also applies. |
|filterSegments|[FilterSegments](#filtersegments)|Represents a collection of filter segments. |
|includeContributions|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether bucket contribution information should be included in the query response metadata. When set to true, the response will contain details about how each bucket contributed to the query result. |
|includeTypes|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Parameter to exclude the type information from the query result. In case not specified, the type information will be included. |
|locale|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The query locale. If none specified, then a language/country neutral locale is chosen. The input values take the ISO-639 Language code with an optional ISO-3166 country code appended to it with an underscore. For instance, both values are valid 'en' or 'en_US'. |
|maxResultBytes|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The maximum number of serialized result bytes. Applies to records only and is a soft limit, i.e. the last record that exceeds the limit will be included in the response completely. No upper limit, no default value. |
|maxResultRecords|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The maximum number of returned query result records. No upper limit. |
|query<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The full query string. |
|queryOptions|[QueryOptions](#queryoptions)|Query options enhance query functionality for Dynatrace internal services. |
|requestTimeoutMilliseconds|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The maximum time the response will be delayed to wait for a result. (This excludes the sending time and time spent in any services between the query-frontend and the client.) If the query finishes within the specified timeout, the query result is returned. Otherwise, the requestToken is returned, allowing polling for the result. |
|timezone|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The query timezone. If none is specified, UTC is used as fallback. The list of valid input values matches that of the IANA Time Zone Database (TZDB). It accepts values in their canonical names like 'Europe/Paris', the abbreviated version like CET or the UTC offset format like '+01:00' |


### DqlQueryParamsContextProps



#### Properties

| Name | Type | Description |
| --- | --- | --- |
|defaultSamplingRatio|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Default sampling ratio. By default no sampling is applied. No upper limit but will be normalized to a power of 10 less than or equal to 100000. |
|defaultScanLimitGbytes|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Default scan limit. Can be overridden in DQL. Default value is configured on application level (see documentation of FETCH command). No upper limit. Use -1 for no limit. |
|defaultTimeframeEnd|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The query timeframe 'end' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'start' parameter is missing, the whole timeframe is ignored. <em>Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.</em> |
|defaultTimeframeStart|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The query timeframe 'start' timestamp in ISO-8601 or RFC3339 format. If the timeframe 'end' parameter is missing, the whole timeframe is ignored. <em>Note that if a timeframe is specified within the query string (query) then it has precedence over this query request parameter.</em> |
|dtClientContext|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The dt-client-context header is an optional string parameter used for monitoring purposes. When included in a request, it helps retrieve information about the execution of the query. It shouldn't hold sensitive information. |
|enablePreview|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Request preview results. If a preview is available within the requestTimeoutMilliseconds, then it will be returned as part of the response. |
|enforceQueryConsumptionLimit|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|(DEPRECATED use body parameter 'enforceQueryConsumptionLimit' instead) If set, query consumption limit will be enforced. |
|enrich|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|If set additional data will be available in the metadata section. |
|fetchTimeoutSeconds|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The time limit for fetching data. Soft limit as further data processing can happen. No upper limit in API but application level default and maximum fetch timeout also applies. |
|filterSegments|[FilterSegments](#filtersegments)|Represents a collection of filter segments. |
|includeContributions|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Indicates whether bucket contribution information should be included in the query response metadata. When set to true, the response will contain details about how each bucket contributed to the query result. |
|includeTypes|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Parameter to exclude the type information from the query result. In case not specified, the type information will be included. |
|locale|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The query locale. If none specified, then a language/country neutral locale is chosen. The input values take the ISO-639 Language code with an optional ISO-3166 country code appended to it with an underscore. For instance, both values are valid 'en' or 'en_US'. |
|maxResultBytes|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The maximum number of serialized result bytes. Applies to records only and is a soft limit, i.e. the last record that exceeds the limit will be included in the response completely. No upper limit, no default value. |
|maxResultRecords|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The maximum number of returned query result records. No upper limit. |
|queryOptions|[QueryOptions](#queryoptions)|Query options enhance query functionality for Dynatrace internal services. |
|requestTimeoutMilliseconds|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The maximum time the response will be delayed to wait for a result. (This excludes the sending time and time spent in any services between the query-frontend and the client.) If the query finishes within the specified timeout, the query result is returned. Otherwise, the requestToken is returned, allowing polling for the result. |
|timezone|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The query timezone. If none is specified, UTC is used as fallback. The list of valid input values matches that of the IANA Time Zone Database (TZDB). It accepts values in their canonical names like 'Europe/Paris', the abbreviated version like CET or the UTC offset format like '+01:00' |


### DssQueryOptions
Options for the DSS query passed to [useGrailFields](#usegrailfields).


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|dataObject<sup>*required</sup>|"logs" &#124; "spans" &#124; "smartscape.nodes" &#124; "metrics"|The target DSS data object (<code>&quot;logs&quot;</code>, <code>&quot;spans&quot;</code>, <code>&quot;smartscape.nodes&quot;</code>, or <code>&quot;metrics&quot;</code>). |
|enabled|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Whether the query is enabled. |
|filterStatement|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Optional DSS filter statement to scope the internal DSS query. |
|requestTimeoutMilliseconds|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Optional timeout in milliseconds for the DSS query request. |
|retry|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number) &#124; [boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Number of retries or boolean to indicate whether to retry on failure. |
|staleTime|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Time in milliseconds before the query is considered stale. |


### FilterSegment
A filter segment is identified by an ID. Each segment includes a list of variable definitions.


#### Properties

| Name | Type |
| --- | --- |
|id<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)| 
|variables|Array&lt;[FilterSegmentVariableDefinition](#filtersegmentvariabledefinition)&gt;| 


### FilterSegmentVariableDefinition
Defines a variable with a name and a list of values.


#### Properties

| Name | Type |
| --- | --- |
|name<sup>*required</sup>|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)| 
|values<sup>*required</sup>|Array&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String)&gt;| 


### FilterSegments
Represents a collection of filter segments.


### GrailFieldQueryOption
A configured query-option object suitable for passing to
`queryClient.prefetchQuery()` or `queryClient.fetchQuery()`.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|enabled|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Whether the query is enabled. |
|queryFn<sup>*required</sup>|(context: \{ signal \}) => Promise&lt;TData&gt;|The function that fetches the data. |
|queryKey<sup>*required</sup>||The query key used for caching and invalidation. |
|retry|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number) &#124; [boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Number of retries or boolean to indicate whether to retry on failure. |
|staleTime|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Time in milliseconds before the query is considered stale. |


### GrailFieldsQueryOptions
Return type of [getGrailFieldsQueryOptions](#getgrailfieldsqueryoptions), containing query options for both autocomplete and DSS queries.


#### Properties

| Name | Type |
| --- | --- |
|autocomplete<sup>*required</sup>|[GrailFieldQueryOption](#grailfieldqueryoption)&lt;AutocompleteResponse&gt;| 
|dss<sup>*required</sup>|[GrailFieldQueryOption](#grailfieldqueryoption)&lt;QueryResult&gt;| 


### QueryOptions
Query options enhance query functionality for Dynatrace internal services.


### QueryOverrides
Subset of `UseQueryOptions` fields (from `@tanstack/react-query`) forwarded to each internal
`useQueries` entry. Mirrors the `enabled`, `staleTime`, and `retry` options.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|enabled|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Whether the query is enabled. |
|retry|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number) &#124; [boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Number of retries or boolean to indicate whether to retry on failure. |
|staleTime|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Time in milliseconds before the query is considered stale. |


### RefetchOptions
Options for the refetch functions returned by the useDql hook.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|cancelRefetch|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<p>If set to <code>true</code>, a currently running request will be cancelled before a new request is made</p> <p>If set to <code>false</code>, no refetch will be made if there is already a request running.</p> <p>Defaults to <code>true</code>.</p>  |
|throwOnError|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)| |


### TypedQueryResult
Generic type that allows to type data returned from Grail.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|metadata<sup>*required</sup>|[UseDqlMetadata](#usedqlmetadata)| |
|records<sup>*required</sup>|Array&lt;T&gt;| |
|types<sup>*required</sup>|Array&lt;RangedFieldTypes&gt;|The data types for the result records. |


### UseDqlGrailMetadata
Collects various bits of metadata information.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|analysisTimeframe|[UseDqlTimeframe](#usedqltimeframe)| |
|canonicalQuery|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The canonical form of the query. It has normalized spaces and canonical constructs. |
|contributions|Contributions| |
|dqlVersion|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The version of DQL that was used to process the query request. |
|executionTimeMilliseconds|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The time it took to execute the query. |
|locale|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Effective locale for the query. |
|notifications|Array&lt;MetadataNotification&gt;|Collected messages during the execution of the query. |
|query|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The submitted query. |
|queryId|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The id of the query |
|sampled|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|True if sampling was used for at least one segment. |
|scannedBytes|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Number of scanned bytes during the query execution. |
|scannedDataPoints|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)| |
|scannedRecords|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Number of scanned records during the query execution. |
|timezone|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Effective timezone for the query. |


### UseDqlMetadata
Collects various bits of metadata information.


#### Properties

| Name | Type |
| --- | --- |
|grail|[UseDqlGrailMetadata](#usedqlgrailmetadata)| 
|metrics|Array&lt;MetricMetadata&gt;| 


### UseDqlOptions
Options for the useDql hook.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|enabled|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Set this to <code>false</code> to disable this query from automatically running. Default: <code>true</code>. |
|placeholderData|[TypedQueryResult](#typedqueryresult)&lt;T&gt;|If set, this value will be used as the placeholder data while the query is still in the <code>loading</code> state. |
|pollRate|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The rate at which Grail query is polled. |
|refetchInterval|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|Query will continuously refetch at this frequency in milliseconds. |
|retryOnMount|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|If set to false, the query will not be retried on mount if it contains an error. Defaults to true. |
|runInBackground|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|If set to <code>true</code>, the query will run in the background and not cancel when switching focus. Default: <code>false</code>. |
|staleTime|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The time in milliseconds after which data is considered stale. |


### UseDqlResult
Represents the possible results of the useDql hook.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|cancel<sup>*required</sup>|() => Promise&lt;void&gt;|Function to call to cancel to ongoing query |
|data|[TypedQueryResult](#typedqueryresult)&lt;T&gt;|The last successfully resolved data for the query. |
|error<sup>*required</sup>|null &#124; Error|The error object for the query, if an error was thrown. |
|forceRefetch<sup>*required</sup>|(options: [RefetchOptions](#refetchoptions)) => Promise&lt;[UseDqlResult](#usedqlresult)&lt;T&gt;&gt;|Function to manually force refetch the query. Ignores stale time. |
|isError<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if the query attempt resulted in an error. |
|isFetched<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if the query has been fetched. |
|isFetching<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> whenever the query is executing, which includes initial pending as well as background refetches. |
|isLoading<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> whenever the first fetch for a query is in-flight. |
|isLoadingError<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Will be <code>true</code> if the query failed while fetching for the first time. |
|isPending<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if there's no cached data and no query attempt was finished yet. |
|isPlaceholderData<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Will be <code>true</code> if the data shown is the placeholder data. |
|isRefetchError<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if the query failed while refetching. |
|isStale<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if the data in the cache is invalidated or if the data is older than the given <code>staleTime</code>. |
|isSuccess<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if the query has received a response with no errors and is ready to display the data. |
|progress<sup>*required</sup>|undefined &#124; [number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|The progress of the query from 0 to 100. |
|refetch<sup>*required</sup>|(options: [RefetchOptions](#refetchoptions)) => Promise&lt;[UseDqlResult](#usedqlresult)&lt;T&gt;&gt;|Function to manually refetch the query. |
|state<sup>*required</sup>|"RUNNING" &#124; "NOT_STARTED" &#124; "SUCCEEDED" &#124; "RESULT_GONE" &#124; "CANCELLED" &#124; "FAILED"|Possible state of the query. |


### UseDqlTimeframe
Represents a timeframe value when no date transformations are applied


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|end|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The end time of the timeframe. |
|start|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|The start time of the timeframe. |


### UseGrailFieldsOptions
Options for the [useGrailFields](#usegrailfields) hook.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|autocompleteQueryOptions<sup>*required</sup>|[AutocompleteQueryOptions](#autocompletequeryoptions)|Options for the autocomplete query, including the DQL query string and optional cache/retry overrides. |
|dssQueryOptions<sup>*required</sup>|[DssQueryOptions](#dssqueryoptions)|Options for the DSS query, including the target data object and optional cache/retry overrides. |
|select|(data: [UseGrailFieldsRaw](#usegrailfieldsraw)) => TData|<p>Selector applied to the raw data object (<code>&#123; autocompleteData, dssData }</code>) once both queries succeed. Use this to transform or filter the raw data before it's returned as <code>data</code>. When omitted, <code>data</code> is the full <a href="#usegrailfieldsraw" target="_blank" rel="noopener noreferrer" >UseGrailFieldsRaw</a> object.</p>  |


### UseGrailFieldsRaw
The raw, unprocessed response data returned by the two underlying queries in [useGrailFields](#usegrailfields).


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|autocompleteData|AutocompleteResponse|Response data from the autocomplete query. |
|dssData|QueryResult|Response data from the DSS query. |


### UseGrailFieldsResult
Return value of the [useGrailFields](#usegrailfields) hook.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|cancel<sup>*required</sup>|() => Promise|Cancels both underlying in-flight requests by aborting their signals via React Query. |
|data<sup>*required</sup>|undefined &#124; TData|The raw response data from both queries (or the value returned by <code>select</code> once both succeed), or <code>undefined</code> while loading. |
|errors<sup>*required</sup>|\{ autocomplete, dss \}|Individual errors from each underlying query (<code>null</code> when that query hasn't errored). |
|errors.autocomplete<sup>*required</sup>|null &#124; Error|Error from the autocomplete query. |
|errors.dss<sup>*required</sup>|null &#124; Error|Error from the DSS query. |
|isError<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> when either query is in an error state. |
|isLoading<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> when either query is still fetching for the first time. |
|isSuccess<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> when both queries have successfully fetched. |
|refetch<sup>*required</sup>|() => Promise&lt;Array&lt;unknown&gt;&gt;|Re-triggers both underlying queries. |


### UseUserBaseResult
Base result shape shared by all `useUser` result states.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|data<sup>*required</sup>|undefined &#124; null &#124; RestUserPublic|The resolved user data, if available. |
|error<sup>*required</sup>|null &#124; Error|The error object, if an error occurred. |
|isError<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if the query attempt resulted in an error. |
|isFetching<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> whenever the query is executing, including background refetches. |
|isLoading<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> whenever the first fetch for a query is in-flight. |
|isPending<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if there's no cached data and no query attempt was finished yet. |
|isSuccess<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if the query has received a response with no errors. |
|refetch<sup>*required</sup>|() => void|Function to manually refetch the user. |


### UseUserErrorResult
Result of the `useUser` hook when an error occurred.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|data<sup>*required</sup>|undefined|The resolved user data, if available. |
|error<sup>*required</sup>|Error|The error object, if an error occurred. |
|isError<sup>*required</sup>|true|<code>true</code> if the query attempt resulted in an error. |
|isFetching<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> whenever the query is executing, including background refetches. |
|isLoading<sup>*required</sup>|false|<code>true</code> whenever the first fetch for a query is in-flight. |
|isPending<sup>*required</sup>|false|<code>true</code> if there's no cached data and no query attempt was finished yet. |
|isSuccess<sup>*required</sup>|false|<code>true</code> if the query has received a response with no errors. |
|refetch<sup>*required</sup>|() => void|Function to manually refetch the user. |


### UseUserLoadingResult
Result of the `useUser` hook while loading.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|data<sup>*required</sup>|undefined|The resolved user data, if available. |
|error<sup>*required</sup>|null|The error object, if an error occurred. |
|isError<sup>*required</sup>|false|<code>true</code> if the query attempt resulted in an error. |
|isFetching<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> whenever the query is executing, including background refetches. |
|isLoading<sup>*required</sup>|true|<code>true</code> whenever the first fetch for a query is in-flight. |
|isPending<sup>*required</sup>|true|<code>true</code> if there's no cached data and no query attempt was finished yet. |
|isSuccess<sup>*required</sup>|false|<code>true</code> if the query has received a response with no errors. |
|refetch<sup>*required</sup>|() => void|Function to manually refetch the user. |


### UseUserOptions
Options for the `useUser` and `useUsers` hooks.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|enabled|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|Set this to <code>false</code> to disable this query from automatically running. Default: <code>true</code>. |
|levelId|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The organizational level ID to use for the IAM API. By default, auto-detected via <code>getEnvironmentId()</code>.</p>  |
|levelType|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|<p>The organizational level type to use for the IAM API. Default: <code>&quot;environment&quot;</code>.</p>  |
|staleTime|[number](https://developer.mozilla.org/en-US/docs/Glossary/Number)|<p>The time in milliseconds after which data is considered stale. Default: <code>300000</code> (5 minutes).</p>  |


### UseUserSuccessResult
Result of the `useUser` hook when the user was successfully fetched.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|data<sup>*required</sup>|null &#124; RestUserPublic|The resolved user data, if available. |
|error<sup>*required</sup>|null|The error object, if an error occurred. |
|isError<sup>*required</sup>|false|<code>true</code> if the query attempt resulted in an error. |
|isFetching<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> whenever the query is executing, including background refetches. |
|isLoading<sup>*required</sup>|false|<code>true</code> whenever the first fetch for a query is in-flight. |
|isPending<sup>*required</sup>|false|<code>true</code> if there's no cached data and no query attempt was finished yet. |
|isSuccess<sup>*required</sup>|true|<code>true</code> if the query has received a response with no errors. |
|refetch<sup>*required</sup>|() => void|Function to manually refetch the user. |


### UseUsersConfig
Configuration for the `UseUsersProvider` context.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|levelId|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Organizational level ID. Default: auto-detected via <code>getEnvironmentId()</code>. |
|levelType|[string](https://developer.mozilla.org/en-US/docs/Glossary/String)|Organizational level type. Default: <code>&quot;environment&quot;</code>. |
|queryClient|QueryClient|Custom TanStack Query client for caching and state management. |


### UseUsersResult
Aggregated result of the `useUsers` hook.


#### Properties

| Name | Type | Description |
| --- | --- | --- |
|data<sup>*required</sup>|Map&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String) &#124; RestUserPublic&gt;|Map of UUID → user data for all successfully resolved users. |
|errors<sup>*required</sup>|Map&lt;[string](https://developer.mozilla.org/en-US/docs/Glossary/String) &#124; Error&gt;|Map of UUID → error for all failed queries. |
|isError<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if any query resulted in an error. |
|isFetching<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if any query is currently fetching (including background refetches). |
|isLoading<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if any query is still loading for the first time. |
|isSuccess<sup>*required</sup>|[boolean](https://developer.mozilla.org/en-US/docs/Glossary/Boolean)|<code>true</code> if all queries have finished successfully. |
|refetch<sup>*required</sup>|() => void|Function to manually refetch all users. |
|users<sup>*required</sup>|Array&lt;RestUserPublic&gt;|Flat array of all successfully resolved users. |