AWS.QBusiness reference

Application

Source: src/AWS/QBusiness/Application.ts

An Amazon Q Business application — the top-level container that indices, retrievers, data sources, and web experiences attach to.

Application: Creating Applications

Identity Center Application

import * as AWS from "alchemy/AWS";

const app = yield* AWS.QBusiness.Application("Assistant", {
  identityCenterInstanceArn: "arn:aws:sso:::instance/ssoins-1234567890abcdef",
  description: "Company knowledge assistant",
});

Anonymous Application

const app = yield* AWS.QBusiness.Application("PublicAssistant", {
  identityType: "ANONYMOUS",
});

AssociatePermission

Source: src/AWS/QBusiness/AssociatePermission.ts

Runtime binding for the AssociatePermission operation (IAM action qbusiness:AssociatePermission), scoped to one Application.

Adds a statement to the application’s permission policy, granting a principal (e.g. an ISV data accessor) cross-account access to Q Business actions. Provide the implementation with Effect.provide(AWS.QBusiness.AssociatePermissionHttp).

AssociatePermission: Cross-Account Permissions

const associate = yield* AWS.QBusiness.AssociatePermission(app);

yield* associate({
  statementId: "isv-search",
  actions: ["qbusiness:SearchRelevantContent"],
  principal: "arn:aws:iam::123456789012:role/IsvRole",
});

BatchDeleteDocument

Source: src/AWS/QBusiness/BatchDeleteDocument.ts

Runtime binding for the BatchDeleteDocument operation (IAM action qbusiness:BatchDeleteDocument), scoped to one Index.

Removes documents from the index by document id. Provide the implementation with Effect.provide(AWS.QBusiness.BatchDeleteDocumentHttp).

BatchDeleteDocument: Document Ingestion

const deleteDocuments = yield* AWS.QBusiness.BatchDeleteDocument(index);

yield* deleteDocuments({ documents: [{ documentId: "welcome" }] });

BatchPutDocument

Source: src/AWS/QBusiness/BatchPutDocument.ts

Runtime binding for the BatchPutDocument operation (IAM action qbusiness:BatchPutDocument), scoped to one Index.

Adds or updates documents in the index directly (the CUSTOM data source path), with optional access controls and enrichment. Provide the implementation with Effect.provide(AWS.QBusiness.BatchPutDocumentHttp).

BatchPutDocument: Document Ingestion

const putDocuments = yield* AWS.QBusiness.BatchPutDocument(index);

const { failedDocuments } = yield* putDocuments({
  documents: [
    {
      id: "welcome",
      title: "Welcome",
      content: { blob: new TextEncoder().encode("Hello Q!") },
      contentType: "PLAIN_TEXT",
    },
  ],
});

CancelSubscription

Source: src/AWS/QBusiness/CancelSubscription.ts

Runtime binding for the CancelSubscription operation (IAM action qbusiness:CancelSubscription), scoped to one Application.

Unsubscribes a user or group; the change takes effect at the next month boundary. Provide the implementation with Effect.provide(AWS.QBusiness.CancelSubscriptionHttp).

CancelSubscription: Subscriptions

const cancel = yield* AWS.QBusiness.CancelSubscription(app);

yield* cancel({ subscriptionId });

ChatSync

Source: src/AWS/QBusiness/ChatSync.ts

Runtime binding for the ChatSync operation (IAM action qbusiness:ChatSync), scoped to one Application.

Sends a user message to the application and returns the full AI-generated answer in one response, including source attributions and any suggested plugin actions. Provide the implementation with Effect.provide(AWS.QBusiness.ChatSyncHttp).

ChatSync: Chat

const chat = yield* AWS.QBusiness.ChatSync(app);

const reply = yield* chat({ userMessage: "What is our travel policy?" });
console.log(reply.systemMessage);

CheckDocumentAccess

Source: src/AWS/QBusiness/CheckDocumentAccess.ts

Runtime binding for the CheckDocumentAccess operation (IAM action qbusiness:CheckDocumentAccess), scoped to one Index.

Checks whether a specific user can access a document, returning the user’s groups/aliases and the document’s ACL evaluation. Provide the implementation with Effect.provide(AWS.QBusiness.CheckDocumentAccessHttp).

CheckDocumentAccess: Document Ingestion

const checkAccess = yield* AWS.QBusiness.CheckDocumentAccess(index);

const { hasAccess } = yield* checkAccess({
  userId: "user@example.com",
  documentId: "welcome",
});

CreateAnonymousWebExperienceUrl

Source: src/AWS/QBusiness/CreateAnonymousWebExperienceUrl.ts

Runtime binding for the CreateAnonymousWebExperienceUrl operation (IAM action qbusiness:CreateAnonymousWebExperienceUrl), scoped to one WebExperience.

Mints a short-lived URL that opens the web experience without authentication (applications created with the ANONYMOUS identity type). Provide the implementation with Effect.provide(AWS.QBusiness.CreateAnonymousWebExperienceUrlHttp).

CreateAnonymousWebExperienceUrl: Anonymous Access

const createUrl =
  yield* AWS.QBusiness.CreateAnonymousWebExperienceUrl(web);

const { anonymousUrl } = yield* createUrl({
  sessionDuration: "30 minutes",
});

CreateSubscription

Source: src/AWS/QBusiness/CreateSubscription.ts

Runtime binding for the CreateSubscription operation (IAM action qbusiness:CreateSubscription), scoped to one Application.

Subscribes an IAM Identity Center user or group to a Q Business pricing tier (Q_LITE or Q_BUSINESS). Provide the implementation with Effect.provide(AWS.QBusiness.CreateSubscriptionHttp).

CreateSubscription: Subscriptions

const subscribe = yield* AWS.QBusiness.CreateSubscription(app);

yield* subscribe({
  principal: { user: idcUserId },
  type: "Q_BUSINESS",
});

CreateUser

Source: src/AWS/QBusiness/CreateUser.ts

Runtime binding for the CreateUser operation (IAM action qbusiness:CreateUser), scoped to one Application.

Creates a user in the application’s user store, mapping the user id to data-source-specific aliases used for document access control. Provide the implementation with Effect.provide(AWS.QBusiness.CreateUserHttp).

CreateUser: User Management

const createUser = yield* AWS.QBusiness.CreateUser(app);

yield* createUser({
  userId: "user@example.com",
  userAliases: [{ userId: "corp\\user" }],
});

DataSource

Source: src/AWS/QBusiness/DataSource.ts

An Amazon Q Business data source — a connector that syncs documents from a repository (S3 bucket, website, SharePoint, …) into an index.

DataSource: Creating Data Sources

S3 Data Source

import * as AWS from "alchemy/AWS";

const source = yield* AWS.QBusiness.DataSource("Docs", {
  applicationId: app.applicationId,
  indexId: index.indexId,
  roleArn: dataSourceRole.roleArn,
  configuration: {
    type: "S3",
    syncMode: "FORCED_FULL_CRAWL",
    connectionConfiguration: {
      repositoryEndpointMetadata: { BucketName: bucket.bucketName },
    },
    repositoryConfigurations: {
      document: {
        fieldMappings: [{
          indexFieldName: "s3_document_id",
          indexFieldType: "STRING",
          dataSourceFieldName: "s3_document_id",
        }],
      },
    },
  },
});

Scheduled Sync

const source = yield* AWS.QBusiness.DataSource("Docs", {
  applicationId: app.applicationId,
  indexId: index.indexId,
  roleArn: dataSourceRole.roleArn,
  syncSchedule: "cron(0 12 * * ? *)",
  configuration: { ... },
});

DeleteAttachment

Source: src/AWS/QBusiness/DeleteAttachment.ts

Runtime binding for the DeleteAttachment operation (IAM action qbusiness:DeleteAttachment), scoped to one Application.

Deletes an attachment associated with a chat conversation. Provide the implementation with Effect.provide(AWS.QBusiness.DeleteAttachmentHttp).

DeleteAttachment: Conversations

const deleteAttachment = yield* AWS.QBusiness.DeleteAttachment(app);

yield* deleteAttachment({ conversationId, attachmentId });

DeleteChatControlsConfiguration

Source: src/AWS/QBusiness/DeleteChatControlsConfiguration.ts

Runtime binding for the DeleteChatControlsConfiguration operation (IAM action qbusiness:DeleteChatControlsConfiguration), scoped to one Application.

Deletes the application’s chat controls configuration. Provide the implementation with Effect.provide(AWS.QBusiness.DeleteChatControlsConfigurationHttp).

DeleteChatControlsConfiguration: Admin Controls

const deleteControls =
  yield* AWS.QBusiness.DeleteChatControlsConfiguration(app);

yield* deleteControls();

DeleteConversation

Source: src/AWS/QBusiness/DeleteConversation.ts

Runtime binding for the DeleteConversation operation (IAM action qbusiness:DeleteConversation), scoped to one Application.

Deletes a chat conversation and its messages. Provide the implementation with Effect.provide(AWS.QBusiness.DeleteConversationHttp).

DeleteConversation: Conversations

const deleteConversation = yield* AWS.QBusiness.DeleteConversation(app);

yield* deleteConversation({ conversationId });

DeleteGroup

Source: src/AWS/QBusiness/DeleteGroup.ts

Runtime binding for the DeleteGroup operation (IAM action qbusiness:DeleteGroup), scoped to one Index.

Deletes a mapped group so its members lose group-scoped document access on the next query. Provide the implementation with Effect.provide(AWS.QBusiness.DeleteGroupHttp).

DeleteGroup: Principal Mapping

const deleteGroup = yield* AWS.QBusiness.DeleteGroup(index);

yield* deleteGroup({ groupName: "engineering" });

DeleteUser

Source: src/AWS/QBusiness/DeleteUser.ts

Runtime binding for the DeleteUser operation (IAM action qbusiness:DeleteUser), scoped to one Application.

Deletes a user from the application user store. Provide the implementation with Effect.provide(AWS.QBusiness.DeleteUserHttp).

DeleteUser: User Management

const deleteUser = yield* AWS.QBusiness.DeleteUser(app);

yield* deleteUser({ userId: "user@example.com" });

DisassociatePermission

Source: src/AWS/QBusiness/DisassociatePermission.ts

Runtime binding for the DisassociatePermission operation (IAM action qbusiness:DisassociatePermission), scoped to one Application.

Removes a statement from the application’s permission policy. Provide the implementation with Effect.provide(AWS.QBusiness.DisassociatePermissionHttp).

DisassociatePermission: Cross-Account Permissions

const disassociate = yield* AWS.QBusiness.DisassociatePermission(app);

yield* disassociate({ statementId: "isv-search" });

GetChatControlsConfiguration

Source: src/AWS/QBusiness/GetChatControlsConfiguration.ts

Runtime binding for the GetChatControlsConfiguration operation (IAM action qbusiness:GetChatControlsConfiguration), scoped to one Application.

Reads the application’s chat controls: response scope, blocked phrases, topic rules, and creator mode. Provide the implementation with Effect.provide(AWS.QBusiness.GetChatControlsConfigurationHttp).

GetChatControlsConfiguration: Admin Controls

const getControls = yield* AWS.QBusiness.GetChatControlsConfiguration(app);

const { responseScope, blockedPhrases } = yield* getControls();

GetDocumentContent

Source: src/AWS/QBusiness/GetDocumentContent.ts

Runtime binding for the GetDocumentContent operation (IAM action qbusiness:GetDocumentContent), scoped to one Index.

Returns a presigned URL for an indexed document’s content, in the raw uploaded format or the extracted text. Provide the implementation with Effect.provide(AWS.QBusiness.GetDocumentContentHttp).

GetDocumentContent: Document Ingestion

const getContent = yield* AWS.QBusiness.GetDocumentContent(index);

const { presignedUrl } = yield* getContent({ documentId: "welcome" });

GetGroup

Source: src/AWS/QBusiness/GetGroup.ts

Runtime binding for the GetGroup operation (IAM action qbusiness:GetGroup), scoped to one Index.

Reads a mapped group’s processing status. Provide the implementation with Effect.provide(AWS.QBusiness.GetGroupHttp).

GetGroup: Principal Mapping

const getGroup = yield* AWS.QBusiness.GetGroup(index);

const { status } = yield* getGroup({ groupName: "engineering" });

GetMedia

Source: src/AWS/QBusiness/GetMedia.ts

Runtime binding for the GetMedia operation (IAM action qbusiness:GetMedia), scoped to one Application.

Fetches the media object (e.g. an extracted image) associated with a chat message. Provide the implementation with Effect.provide(AWS.QBusiness.GetMediaHttp).

GetMedia: Conversations

const getMedia = yield* AWS.QBusiness.GetMedia(app);

const media = yield* getMedia({ conversationId, messageId, mediaId });

GetPolicy

Source: src/AWS/QBusiness/GetPolicy.ts

Runtime binding for the GetPolicy operation (IAM action qbusiness:GetPolicy), scoped to one Application.

Reads the application’s resource-based permission policy (the statements ISV data accessors were granted). Provide the implementation with Effect.provide(AWS.QBusiness.GetPolicyHttp).

GetPolicy: Cross-Account Permissions

const getPolicy = yield* AWS.QBusiness.GetPolicy(app);

const { policy } = yield* getPolicy();

GetUser

Source: src/AWS/QBusiness/GetUser.ts

Runtime binding for the GetUser operation (IAM action qbusiness:GetUser), scoped to one Application.

Reads a user’s alias mappings from the application user store. Provide the implementation with Effect.provide(AWS.QBusiness.GetUserHttp).

GetUser: User Management

const getUser = yield* AWS.QBusiness.GetUser(app);

const { userAliases } = yield* getUser({ userId: "user@example.com" });

ListAttachments

Source: src/AWS/QBusiness/ListAttachments.ts

Runtime binding for the ListAttachments operation (IAM action qbusiness:ListAttachments), scoped to one Application.

Lists the files attached to chat conversations. Provide the implementation with Effect.provide(AWS.QBusiness.ListAttachmentsHttp).

ListAttachments: Conversations

const listAttachments = yield* AWS.QBusiness.ListAttachments(app);

const { attachments } = yield* listAttachments({ conversationId });

ListConversations

Source: src/AWS/QBusiness/ListConversations.ts

Runtime binding for the ListConversations operation (IAM action qbusiness:ListConversations), scoped to one Application.

Lists a user’s chat conversations in the application. Provide the implementation with Effect.provide(AWS.QBusiness.ListConversationsHttp).

ListConversations: Conversations

const listConversations = yield* AWS.QBusiness.ListConversations(app);

const { conversations } = yield* listConversations();

ListDataSourceSyncJobs

Source: src/AWS/QBusiness/ListDataSourceSyncJobs.ts

Runtime binding for the ListDataSourceSyncJobs operation (IAM action qbusiness:ListDataSourceSyncJobs), scoped to one DataSource.

Lists the data source’s synchronization job history. Provide the implementation with Effect.provide(AWS.QBusiness.ListDataSourceSyncJobsHttp).

ListDataSourceSyncJobs: Data Source Sync

const listSyncJobs = yield* AWS.QBusiness.ListDataSourceSyncJobs(source);

const { history } = yield* listSyncJobs();

ListDocuments

Source: src/AWS/QBusiness/ListDocuments.ts

Runtime binding for the ListDocuments operation (IAM action qbusiness:ListDocuments), scoped to one Index.

Lists the documents the index holds and their ingestion status. Provide the implementation with Effect.provide(AWS.QBusiness.ListDocumentsHttp).

ListDocuments: Document Ingestion

const listDocuments = yield* AWS.QBusiness.ListDocuments(index);

const { documentDetailList } = yield* listDocuments();

ListGroups

Source: src/AWS/QBusiness/ListGroups.ts

Runtime binding for the ListGroups operation (IAM action qbusiness:ListGroups), scoped to one Index.

Lists the groups mapped into the index before a given time. Provide the implementation with Effect.provide(AWS.QBusiness.ListGroupsHttp).

ListGroups: Principal Mapping

const listGroups = yield* AWS.QBusiness.ListGroups(index);

const { items } = yield* listGroups({ updatedEarlierThan: new Date() });

ListMessages

Source: src/AWS/QBusiness/ListMessages.ts

Runtime binding for the ListMessages operation (IAM action qbusiness:ListMessages), scoped to one Application.

Lists the messages of a chat conversation. Provide the implementation with Effect.provide(AWS.QBusiness.ListMessagesHttp).

ListMessages: Conversations

const listMessages = yield* AWS.QBusiness.ListMessages(app);

const { messages } = yield* listMessages({ conversationId });

ListSubscriptions

Source: src/AWS/QBusiness/ListSubscriptions.ts

Runtime binding for the ListSubscriptions operation (IAM action qbusiness:ListSubscriptions), scoped to one Application.

Lists the application’s user and group subscriptions. Provide the implementation with Effect.provide(AWS.QBusiness.ListSubscriptionsHttp).

ListSubscriptions: Subscriptions

const listSubscriptions = yield* AWS.QBusiness.ListSubscriptions(app);

const { subscriptions } = yield* listSubscriptions();

PutFeedback

Source: src/AWS/QBusiness/PutFeedback.ts

Runtime binding for the PutFeedback operation (IAM action qbusiness:PutFeedback), scoped to one Application.

Records end-user usefulness feedback (thumbs up/down and reasons) for a chat message, which Amazon Q Business uses to improve response quality. Provide the implementation with Effect.provide(AWS.QBusiness.PutFeedbackHttp).

PutFeedback: Chat

const feedback = yield* AWS.QBusiness.PutFeedback(app);

yield* feedback({
  conversationId: reply.conversationId!,
  messageId: reply.systemMessageId!,
  messageUsefulness: {
    usefulness: "USEFUL",
    submittedAt: new Date(),
  },
});

PutGroup

Source: src/AWS/QBusiness/PutGroup.ts

Runtime binding for the PutGroup operation (IAM action qbusiness:PutGroup), scoped to one Index.

Creates or replaces a group’s membership (users and sub groups) used to enforce document access control at query time. Provide the implementation with Effect.provide(AWS.QBusiness.PutGroupHttp).

PutGroup: Principal Mapping

const putGroup = yield* AWS.QBusiness.PutGroup(index);

yield* putGroup({
  groupName: "engineering",
  type: "INDEX",
  groupMembers: {
    memberUsers: [{ userId: "user@example.com", type: "INDEX" }],
  },
});

Retriever

Source: src/AWS/QBusiness/Retriever.ts

An Amazon Q Business retriever — the query engine that fetches relevant passages from an index (native or Kendra) to ground chat responses.

Retriever: Creating Retrievers

Native Index Retriever

import * as AWS from "alchemy/AWS";

const retriever = yield* AWS.QBusiness.Retriever("Docs", {
  applicationId: app.applicationId,
  type: "NATIVE_INDEX",
  configuration: {
    nativeIndexConfiguration: { indexId: index.indexId },
  },
});

Kendra Index Retriever

const retriever = yield* AWS.QBusiness.Retriever("Kendra", {
  applicationId: app.applicationId,
  type: "KENDRA_INDEX",
  roleArn: role.roleArn,
  configuration: {
    kendraIndexConfiguration: { indexId: kendraIndex.id },
  },
});

Index

Source: src/AWS/QBusiness/SearchIndex.ts

An Amazon Q Business index — the document store that data sources sync content into and retrievers query.

Index: Creating Indexes

Starter Index

import * as AWS from "alchemy/AWS";

const index = yield* AWS.QBusiness.Index("Docs", {
  applicationId: app.applicationId,
});

Enterprise Index with Extra Capacity

const index = yield* AWS.QBusiness.Index("Docs", {
  applicationId: app.applicationId,
  type: "ENTERPRISE",
  capacityConfiguration: { units: 2 },
});

SearchRelevantContent

Source: src/AWS/QBusiness/SearchRelevantContent.ts

Runtime binding for the SearchRelevantContent operation (IAM action qbusiness:SearchRelevantContent), scoped to one Application.

Searches an application’s indexed content through a retriever and returns the relevant passages without generating an answer — the RAG retrieval half on its own. Provide the implementation with Effect.provide(AWS.QBusiness.SearchRelevantContentHttp).

SearchRelevantContent: Content Retrieval

const search = yield* AWS.QBusiness.SearchRelevantContent(app);

const results = yield* search({
  queryText: "expense reimbursement deadline",
  contentSource: { retriever: { retrieverId: retriever.retrieverId } },
});

StartDataSourceSyncJob

Source: src/AWS/QBusiness/StartDataSourceSyncJob.ts

Runtime binding for the StartDataSourceSyncJob operation (IAM action qbusiness:StartDataSourceSyncJob), scoped to one DataSource.

Starts a synchronization job that crawls the connector and ingests its content into the index. Provide the implementation with Effect.provide(AWS.QBusiness.StartDataSourceSyncJobHttp).

StartDataSourceSyncJob: Data Source Sync

const startSync = yield* AWS.QBusiness.StartDataSourceSyncJob(source);

const { executionId } = yield* startSync();

StopDataSourceSyncJob

Source: src/AWS/QBusiness/StopDataSourceSyncJob.ts

Runtime binding for the StopDataSourceSyncJob operation (IAM action qbusiness:StopDataSourceSyncJob), scoped to one DataSource.

Stops the data source’s running synchronization job. Provide the implementation with Effect.provide(AWS.QBusiness.StopDataSourceSyncJobHttp).

StopDataSourceSyncJob: Data Source Sync

const stopSync = yield* AWS.QBusiness.StopDataSourceSyncJob(source);

yield* stopSync();

UpdateChatControlsConfiguration

Source: src/AWS/QBusiness/UpdateChatControlsConfiguration.ts

Runtime binding for the UpdateChatControlsConfiguration operation (IAM action qbusiness:UpdateChatControlsConfiguration), scoped to one Application.

Updates the application’s chat controls — response scope, blocked phrases, topic rules, creator mode, and hallucination reduction. Provide the implementation with Effect.provide(AWS.QBusiness.UpdateChatControlsConfigurationHttp).

UpdateChatControlsConfiguration: Admin Controls

const updateControls =
  yield* AWS.QBusiness.UpdateChatControlsConfiguration(app);

yield* updateControls({ responseScope: "ENTERPRISE_CONTENT_ONLY" });

UpdateSubscription

Source: src/AWS/QBusiness/UpdateSubscription.ts

Runtime binding for the UpdateSubscription operation (IAM action qbusiness:UpdateSubscription), scoped to one Application.

Changes an existing subscription’s pricing tier. Provide the implementation with Effect.provide(AWS.QBusiness.UpdateSubscriptionHttp).

UpdateSubscription: Subscriptions

const updateSubscription = yield* AWS.QBusiness.UpdateSubscription(app);

yield* updateSubscription({ subscriptionId, type: "Q_LITE" });

UpdateUser

Source: src/AWS/QBusiness/UpdateUser.ts

Runtime binding for the UpdateUser operation (IAM action qbusiness:UpdateUser), scoped to one Application.

Adds and removes alias mappings for a user. Provide the implementation with Effect.provide(AWS.QBusiness.UpdateUserHttp).

UpdateUser: User Management

const updateUser = yield* AWS.QBusiness.UpdateUser(app);

yield* updateUser({
  userId: "user@example.com",
  userAliasesToUpdate: [{ userId: "corp\\user" }],
});

WebExperience

Source: src/AWS/QBusiness/WebExperience.ts

An Amazon Q Business web experience — the hosted chat UI end users open to converse with an application.

WebExperience: Creating Web Experiences

Basic Web Experience

import * as AWS from "alchemy/AWS";

const web = yield* AWS.QBusiness.WebExperience("Chat", {
  applicationId: app.applicationId,
  title: "Company Assistant",
  welcomeMessage: "Ask me anything about our docs.",
});

Embeddable Web Experience

const web = yield* AWS.QBusiness.WebExperience("Chat", {
  applicationId: app.applicationId,
  origins: ["https://intranet.example.com"],
  samplePromptsControlMode: "ENABLED",
});