q_apps

Creates, updates, deletes, gets or lists a q_apps resource.

Overview

Name	q_apps
Type	Resource
Id	aws.qapps.q_apps

Fields

The following fields are returned by SELECT queries:

get_q_app

Name	Datatype	Description
app_arn	string	The Amazon Resource Name (ARN) of the Q App.
app_definition	object	The full definition of the Q App, specifying the cards and flow.
app_id	string	The unique identifier of the Q App. (pattern: <code>[\da-f]{8}-[\da-f]{4}-[45][\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}</code>)
app_version	integer	The version of the Q App.
created_at	string (date-time)	The date and time the Q App was created.
created_by	string	The user who created the Q App.
description	string	The description of the Q App.
initial_prompt	string	The initial prompt displayed when the Q App is started.
required_capabilities	array	The capabilities required to run the Q App, such as file upload or third-party integrations.
status	string	The status of the Q App. (PUBLISHED, DRAFT, DELETED)
title_	string	The title of the Q App. (pattern: <code>[^{}\"<>]+</code>)
updated_at	string (date-time)	The date and time the Q App was last updated.
updated_by	string	The user who last updated the Q App.

list_q_apps

Name	Datatype	Description
app_arn	string	The Amazon Resource Name (ARN) of the Q App.
app_id	string	The unique identifier of the Q App. (pattern: <code>[\da-f]{8}-[\da-f]{4}-[45][\da-f]{3}-[89ABab][\da-f]{3}-[\da-f]{12}</code>)
can_edit	boolean	A flag indicating whether the user can edit the Q App.
created_at	string (date-time)	The date and time the user's association with the Q App was created.
description	string	The description of the Q App.
is_verified	boolean	Indicates whether the Q App has been verified.
status	string	The status of the user's association with the Q App.
title_	string	The title of the Q App. (pattern: <code>[^{}\"<>]+</code>)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get_q_app	select	instance-id, appId, region	appVersion	Retrieves the full details of an Q App, including its definition specifying the cards and flow.
list_q_apps	select	instance-id, region	limit, nextToken	Lists the Amazon Q Apps owned by or associated with the user either because they created it or because they used it from the library in the past. The user identity is extracted from the credentials used to invoke this operation..
create_q_app	insert	instance-id, region, title, appDefinition		Creates a new Amazon Q App based on the provided definition. The Q App definition specifies the cards and flow of the Q App. This operation also calculates the dependencies between the cards by inspecting the references in the prompts.
update_q_app	update	instance-id, region, appId		Updates an existing Amazon Q App, allowing modifications to its title, description, and definition.
delete_q_app	delete	instance-id, region		Deletes an Amazon Q App owned by the user. If the Q App was previously published to the library, it is also removed from the library.
associate_q_app_with_user	exec	instance-id, region, appId		This operation creates a link between the user's identity calling the operation and a specific Q App. This is useful to mark the Q App as a favorite for the user if the user doesn't own the Amazon Q App so they can still run it and see it in their inventory of Q Apps.
disassociate_q_app_from_user	exec	instance-id, region, appId		Disassociates a Q App from a user removing the user's access to run the Q App.
start_q_app_session	exec	instance-id, region, appId, appVersion		Starts a new session for an Amazon Q App, allowing inputs to be provided and the app to be run. Each Q App session will be condensed into a single conversation in the web experience.
stop_q_app_session	exec	instance-id, region, sessionId		Stops an active session for an Amazon Q App.This deletes all data related to the session and makes it invalid for future uses. The results of the session will be persisted as part of the conversation.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
appId	string	The unique identifier of the Q App to retrieve.
instance-id	string	The unique identifier of the Amazon Q Business application environment instance.
region	string	AWS region (default: us-east-1)
appVersion	integer	The version of the Q App.
limit	integer	The maximum number of Q Apps to return in the response.
nextToken	string	The token to request the next page of results.

SELECT examples

get_q_app

Retrieves the full details of an Q App, including its definition specifying the cards and flow.

SELECT
app_arn,
app_definition,
app_id,
app_version,
created_at,
created_by,
description,
initial_prompt,
required_capabilities,
status,
title_,
updated_at,
updated_by
FROM aws.qapps.q_apps
WHERE `instance-id` = '{{ instance-id }}' -- required
AND appId = '{{ appId }}' -- required
AND region = '{{ region }}' -- required
AND appVersion = '{{ appVersion }}'
;

list_q_apps

Lists the Amazon Q Apps owned by or associated with the user either because they created it or because they used it from the library in the past. The user identity is extracted from the credentials used to invoke this operation..

SELECT
app_arn,
app_id,
can_edit,
created_at,
description,
is_verified,
status,
title_
FROM aws.qapps.q_apps
WHERE `instance-id` = '{{ instance-id }}' -- required
AND region = '{{ region }}' -- required
AND limit = '{{ limit }}'
AND nextToken = '{{ nextToken }}'
;

INSERT examples

create_q_app

Creates a new Amazon Q App based on the provided definition. The Q App definition specifies the cards and flow of the Q App. This operation also calculates the dependencies between the cards by inspecting the references in the prompts.

INSERT INTO aws.qapps.q_apps (
title,
description,
appDefinition,
tags,
`instance-id`,
region
)
SELECT 
'{{ title }}' /* required */,
'{{ description }}',
'{{ appDefinition }}' /* required */,
'{{ tags }}',
'{{ instance-id }}',
'{{ region }}'
RETURNING
app_arn,
app_id,
app_version,
created_at,
created_by,
description,
initial_prompt,
required_capabilities,
status,
title_,
updated_at,
updated_by
;

Manifest

# Description fields are for documentation purposes
- name: q_apps
props:
  - name: instance-id
    value: "{{ instance-id }}"
    description: Required parameter for the q_apps resource.
  - name: region
    value: "{{ region }}"
    description: Required parameter for the q_apps resource.
  - name: title
    value: "{{ title }}"
  - name: description
    value: "{{ description }}"
  - name: appDefinition
    description: |
      The input for defining an Q App.
    value:
      cards:
        - textInput:
            title_: "{{ title_ }}"
            id: "{{ id }}"
            type_: "{{ type_ }}"
            placeholder: "{{ placeholder }}"
            defaultValue: "{{ defaultValue }}"
          qQuery:
            title_: "{{ title_ }}"
            id: "{{ id }}"
            type_: "{{ type_ }}"
            prompt: "{{ prompt }}"
            outputSource: "{{ outputSource }}"
            attributeFilter:
              andAllFilters:
                - andAllFilters: "{{ andAllFilters }}"
                  orAllFilters: "{{ orAllFilters }}"
                  notFilter:
                    andAllFilters: "{{ andAllFilters }}"
                    orAllFilters: "{{ orAllFilters }}"
                    notFilter: "{{ notFilter }}"
                    equalsTo: "{{ equalsTo }}"
                    containsAll: "{{ containsAll }}"
                    containsAny: "{{ containsAny }}"
                    greaterThan: "{{ greaterThan }}"
                    greaterThanOrEquals: "{{ greaterThanOrEquals }}"
                    lessThan: "{{ lessThan }}"
                    lessThanOrEquals: "{{ lessThanOrEquals }}"
                  equalsTo:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  containsAll:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  containsAny:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  greaterThan:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  greaterThanOrEquals:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  lessThan:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  lessThanOrEquals:
                    name: "{{ name }}"
                    value: "{{ value }}"
              orAllFilters:
                - andAllFilters: "{{ andAllFilters }}"
                  orAllFilters: "{{ orAllFilters }}"
                  notFilter:
                    andAllFilters: "{{ andAllFilters }}"
                    orAllFilters: "{{ orAllFilters }}"
                    notFilter: "{{ notFilter }}"
                    equalsTo: "{{ equalsTo }}"
                    containsAll: "{{ containsAll }}"
                    containsAny: "{{ containsAny }}"
                    greaterThan: "{{ greaterThan }}"
                    greaterThanOrEquals: "{{ greaterThanOrEquals }}"
                    lessThan: "{{ lessThan }}"
                    lessThanOrEquals: "{{ lessThanOrEquals }}"
                  equalsTo:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  containsAll:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  containsAny:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  greaterThan:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  greaterThanOrEquals:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  lessThan:
                    name: "{{ name }}"
                    value: "{{ value }}"
                  lessThanOrEquals:
                    name: "{{ name }}"
                    value: "{{ value }}"
              notFilter:
                andAllFilters: "{{ andAllFilters }}"
                orAllFilters: "{{ orAllFilters }}"
                notFilter: "{{ notFilter }}"
                equalsTo: "{{ equalsTo }}"
                containsAll: "{{ containsAll }}"
                containsAny: "{{ containsAny }}"
                greaterThan: "{{ greaterThan }}"
                greaterThanOrEquals: "{{ greaterThanOrEquals }}"
                lessThan: "{{ lessThan }}"
                lessThanOrEquals: "{{ lessThanOrEquals }}"
              equalsTo:
                name: "{{ name }}"
                value: "{{ value }}"
              containsAll:
                name: "{{ name }}"
                value: "{{ value }}"
              containsAny:
                name: "{{ name }}"
                value: "{{ value }}"
              greaterThan:
                name: "{{ name }}"
                value: "{{ value }}"
              greaterThanOrEquals:
                name: "{{ name }}"
                value: "{{ value }}"
              lessThan:
                name: "{{ name }}"
                value: "{{ value }}"
              lessThanOrEquals:
                name: "{{ name }}"
                value: "{{ value }}"
          qPlugin:
            title_: "{{ title_ }}"
            id: "{{ id }}"
            type_: "{{ type_ }}"
            prompt: "{{ prompt }}"
            pluginId: "{{ pluginId }}"
            actionIdentifier: "{{ actionIdentifier }}"
          fileUpload:
            title_: "{{ title_ }}"
            id: "{{ id }}"
            type_: "{{ type_ }}"
            filename: "{{ filename }}"
            fileId: "{{ fileId }}"
            allowOverride: {{ allowOverride }}
          formInput:
            title_: "{{ title_ }}"
            id: "{{ id }}"
            type_: "{{ type_ }}"
            metadata:
              schema: "{{ schema }}"
            computeMode: "{{ computeMode }}"
      initialPrompt: "{{ initialPrompt }}"
  - name: tags
    value: "{{ tags }}"

UPDATE examples

update_q_app

Updates an existing Amazon Q App, allowing modifications to its title, description, and definition.

UPDATE aws.qapps.q_apps
SET 
appId = '{{ appId }}',
title = '{{ title }}',
description = '{{ description }}',
appDefinition = '{{ appDefinition }}'
WHERE 
`instance-id` = '{{ instance-id }}' --required
AND region = '{{ region }}' --required
AND appId = '{{ appId }}' --required
RETURNING
app_arn,
app_id,
app_version,
created_at,
created_by,
description,
initial_prompt,
required_capabilities,
status,
title_,
updated_at,
updated_by;

DELETE examples

delete_q_app

Deletes an Amazon Q App owned by the user. If the Q App was previously published to the library, it is also removed from the library.

DELETE FROM aws.qapps.q_apps
WHERE `instance-id` = '{{ instance-id }}' --required
AND region = '{{ region }}' --required
;

Lifecycle Methods

associate_q_app_with_user

This operation creates a link between the user's identity calling the operation and a specific Q App. This is useful to mark the Q App as a favorite for the user if the user doesn't own the Amazon Q App so they can still run it and see it in their inventory of Q Apps.

EXEC aws.qapps.q_apps.associate_q_app_with_user 
@instance-id='{{ instance-id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"appId": "{{ appId }}"
}'
;

disassociate_q_app_from_user

Disassociates a Q App from a user removing the user's access to run the Q App.

EXEC aws.qapps.q_apps.disassociate_q_app_from_user 
@instance-id='{{ instance-id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"appId": "{{ appId }}"
}'
;

start_q_app_session

Starts a new session for an Amazon Q App, allowing inputs to be provided and the app to be run. Each Q App session will be condensed into a single conversation in the web experience.

EXEC aws.qapps.q_apps.start_q_app_session 
@instance-id='{{ instance-id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"appId": "{{ appId }}", 
"appVersion": {{ appVersion }}, 
"initialValues": "{{ initialValues }}", 
"sessionId": "{{ sessionId }}", 
"tags": "{{ tags }}"
}'
;

stop_q_app_session

Stops an active session for an Amazon Q App.This deletes all data related to the session and makes it invalid for future uses. The results of the session will be persisted as part of the conversation.

EXEC aws.qapps.q_apps.stop_q_app_session 
@instance-id='{{ instance-id }}' --required, 
@region='{{ region }}' --required 
@@json=
'{
"sessionId": "{{ sessionId }}"
}'
;