> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firebolt.io/llms.txt
> Use this file to discover all available pages before exploring further.

> Invoke an Amazon Bedrock model and return the raw response as JSON text.

# AWS_BEDROCK_AI_QUERY

Invokes an Amazon AWS Bedrock model and returns the raw response payload as a JSON string (`TEXT`).
To use the function, provide the model identifier, the request body as serialized JSON, and a `LOCATION` that holds AWS credentials.

For setup guidance and end-to-end examples, see [Getting started with AI](/guides/ai/getting-started-with-ai).

## Syntax

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
AWS_BEDROCK_AI_QUERY(<model>, <request>, <location> [, <null_on_error>])
```

## Parameters

| Parameter         | Description                                                                                                                                                                                 | Supported input types |
| :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :-------------------- |
| `<model>`         | The model to invoke. Use a Bedrock model identifier (for example, `'amazon.nova-lite-v1:0'`, `'meta.llama3-3-70b-instruct-v1:0'`). The value is forwarded to Bedrock without validation.    | `TEXT`                |
| `<request>`       | The request body as a serialized JSON string. The structure and fields must follow the syntax for the selected model.                                                                       | `TEXT`                |
| `<location>`      | The name of the `LOCATION` to use for AWS credentials. Must be a literal constant. See [CREATE LOCATION (Amazon Bedrock)](/reference-sql/commands/data-definition/create-location-bedrock). | `TEXT`                |
| `<null_on_error>` | Optional. Whether to return `NULL` instead of raising an error when a Bedrock invocation error occurs. Default `FALSE`. Must be a literal constant.                                         | `BOOL`                |

<Note>
  Make sure the `request` JSON matches the syntax required by the model you select. See the [Amazon Bedrock model parameters documentation](https://docs.aws.amazon.com/bedrock/latest/userguide/model-parameters.html) for details.
</Note>

## Return Type

`TEXT`

* Returns the raw Bedrock response payload as a JSON string.
* If `<request>` is `NULL`, the function returns `NULL`.

## LLM Token Budget

The daily LLM token budget for each account is governed by the [`ALTER ACCOUNT SET LLM_TOKEN_BUDGET`](/reference-sql/commands/data-definition/alter-account/#alter-account-set-llm-token-budget) command. If your account exceeds its allotted token budget, invocations of `AWS_BEDROCK_AI_QUERY` will fail until the budget is increased or the daily limit resets. The current limit and daily usage of the LLM token budget can be viewed in [information\_schema.quotas](/reference-sql/information-schema/quotas).

Counting tokens is done in a "best effort" manner. Some models provide the token count in the response, while others don't. For those that don't Firebolt estimates the token count. Supported model list:

| Model ID substring | Token count support |
| ------------------ | ------------------- |
| `amazon.nova`      | Accurate            |
| `amazon.titan`     | Accurate            |
| `anthropic.claude` | Accurate            |
| `cohere.command`   | Estimated           |
| `cohere-command-r` | Accurate            |
| `deepseek`         | Estimated           |
| `meta.llama`       | Accurate            |
| `mistral`          | Estimated           |

<Note>
  LLM token budget accounting is not available in Firebolt Core.
</Note>

## Examples

### Create a LOCATION with role ARN

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
CREATE LOCATION my_bedrock_location WITH
    SOURCE = 'AMAZON_BEDROCK'
    CREDENTIALS = (AWS_ROLE_ARN = '<aws_role_arn>');
```

For details on creating a Bedrock LOCATION, see [CREATE LOCATION (Amazon Bedrock)](/reference-sql/commands/data-definition/create-location-bedrock).

### Invoke a model using the LOCATION

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT AWS_BEDROCK_AI_QUERY(
    'amazon.nova-micro-v1:0',
    $${"schemaVersion": "messages-v1", "messages": [{"role": "user","content": [{"text": "What is the company name that aws belongs to?"}]}],"system": [{"text": "Fulfill the user's request"}],"inferenceConfig": {}}$$,
    'my_bedrock_location') AS result;
```

**Returns (example shape):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{"output":{"message":{"content":[{"text":"Amazon Web Services is part of Amazon."}],"role":"assistant"}},"stopReason":"end_turn","usage":{"inputTokens":18,"outputTokens":42,"totalTokens":60}}
```

### Invoking the LLM on multiple values

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT n AS number,
       JSON_POINTER_EXTRACT_TEXT(
         AWS_BEDROCK_AI_QUERY(
           'amazon.nova-micro-v1:0',
           $${"schemaVersion": "messages-v1", "messages": [{"role": "user","content": [{"text": "$$ || n::TEXT || $$"}]}],"system": [{"text": "Write in english the capitalized name of the number that the user writes. Respond with a single word."}],"inferenceConfig": {}}$$,
           'my_bedrock_location'
         ),
         '/output/message/content/0/text'
       ) AS processed
FROM generate_series(1,3) s(n);
```

**Returns**

| number | processed |
| :----- | :-------- |
| 1      | 'ONE'     |
| 2      | 'TWO'     |
| 3      | 'THREE'   |

### Sentiment analysis

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT JSON_POINTER_EXTRACT_TEXT(
  AWS_BEDROCK_AI_QUERY(
    'amazon.nova-micro-v1:0',
    $${"schemaVersion": "messages-v1", "messages": [{"role": "user","content": [{"text": "I love Firebolt."}]}],"system": [{"text": "Identify the sentiment in the user's sentence as a single uppercase word: POSITIVE or NEGATIVE. Respond with a single word."}],"inferenceConfig": {}}$$,
    'my_bedrock_location'
  ),
  '/output/message/content/0/text'
);
```

**Returns**

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
'POSITIVE'
```

### Check your LLM token quota usage

```sql theme={"theme":{"light":"github-light","dark":"github-dark"}}
SELECT * FROM account_db.information_schema.quotas;
```

Look for the `LLM_TOKEN_BUDGET` row to view current usage and limits.