QuickSight / Client / create_knowledge_base

create_knowledge_base¶

QuickSight.Client.create_knowledge_base(**kwargs)¶

Creates a knowledge base from a specified data source. Supported data source connector types include:

S3_KNOWLEDGE_BASE – Uses an Amazon S3 bucket as the data source.
WEB_CRAWLER – Uses web pages indexed by the built-in web crawler as the data source.
GOOGLE_DRIVE – Uses Google Drive as the data source. Supports service account authentication only.
SHAREPOINT – Uses SharePoint as the data source. Supports two-legged OAuth only.
ONE_DRIVE – Uses OneDrive as the data source. Supports two-legged OAuth only.

Request Syntax

response = client.create_knowledge_base(
    AwsAccountId='string',
    KnowledgeBaseId='string',
    Name='string',
    DataSourceArn='string',
    KnowledgeBaseConfiguration={
        'templateConfiguration': {
            'template': {...}|[...]|123|123.4|'string'|True|None
        }
    },
    Description='string',
    Permissions=[
        {
            'Principal': 'string',
            'Actions': [
                'string',
            ]
        },
    ],
    MediaExtractionConfiguration={
        'imageExtractionConfiguration': {
            'imageExtractionStatus': 'ENABLED'|'DISABLED'
        },
        'audioExtractionConfiguration': {
            'audioExtractionStatus': 'ENABLED'|'DISABLED'
        },
        'videoExtractionConfiguration': {
            'videoExtractionStatus': 'ENABLED'|'DISABLED',
            'videoExtractionType': 'AUDIO_TRANSCRIPTION_ONLY'|'VISUAL_CONTENT_AND_AUDIO_TRANSCRIPTION'
        }
    },
    AccessControlConfiguration={
        'isACLEnabled': True|False
    },
    PrimaryOwnerArn='string',
    Tags=[
        {
            'Key': 'string',
            'Value': 'string'
        },
    ]
)

Parameters:

AwsAccountId (string) –
[REQUIRED]

The ID of the Amazon Web Services account that contains the knowledge base.
KnowledgeBaseId (string) –
[REQUIRED]

The unique identifier for the knowledge base.
Name (string) –
[REQUIRED]

The name of the knowledge base.
DataSourceArn (string) –
[REQUIRED]

The Amazon Resource Name (ARN) of the data source for the knowledge base.
KnowledgeBaseConfiguration (dict) –
[REQUIRED]

The configuration settings for a knowledge base.
- templateConfiguration (dict) –
  
  The template configuration that defines how the data source connector crawls and indexes data for the knowledge base. The template structure varies by connector type. See KbTemplateConfiguration for connector-specific details.
  - template (document) –
    
    The connector configuration for the knowledge base data source. The structure depends on the connector type of the data source referenced by DataSourceArn.
    
    The template must be a JSON object. All connector types share the following top-level keys. The value of type and the contents of connectionConfiguration vary by connector type.
    - type – (Required) The connector type of the data source. This value identifies the connector. Valid values: S3V2, WEBCRAWLERV3, GOOGLEDRIVEV3, ONEDRIVEV3, SHAREPOINTV3. For the fields required by each connector, see the connector-specific list that follows.
    - connectionConfiguration – (Required) The connection details for the data source. The keys in this object vary by connector type; see the connector-specific list that follows.
    - filterConfiguration – (Optional) Rules that determine which content is crawled, such as inclusion and exclusion prefixes, patterns, or file-size limits.
    - accessControlConfiguration – (Optional) Document-level access control (ACL) settings. Supported by all connector types except Web Crawler ( WEBCRAWLERV3). The available fields depend on the connector type.
    - deletionProtectionConfiguration – (Optional) Deletion-protection settings, supported by all connector types. Contains enableDeletionProtection (Boolean) and deletionProtectionThreshold (String; a value from 1 to 100).
    The following list describes the valid type value, the connectionConfiguration contents, and any connector-specific fields for each connector type:
    - Amazon S3 ( type: S3V2) – The type value must be S3V2. connectionConfiguration is required and contains:
      - bucketName – (Required) The name of the Amazon S3 bucket to crawl. Type: String. Length: 3–63 characters. Pattern: ^[a-z0-9][.\-a-z0-9]{1,61}[a-z0-9]$.
      - bucketOwnerAccountId – (Required) The ID of the AWS account that owns the bucket. Type: String. Pattern: ^\d{12}$.
    Amazon S3 supports the following optional filterConfiguration fields:
    inclusionPrefixes or exclusionPrefixes – Amazon S3 key prefixes to include or exclude. Type: Array of String. Up to 350 items, each 1–1,024 characters.
    
    inclusionPatterns or exclusionPatterns – Patterns to include or exclude objects. Type: Array of String. Up to 350 items, each 1–1,024 characters.
    
    maxFileSizeInMegaBytes – The maximum size, in MB, of a file to ingest. Type: String. Pattern: ^\d+$.
    For Amazon S3, accessControlConfiguration supports the following fields:
    crawlAcl – Specifies whether the connector crawls and enforces document access control lists (ACLs). Type: Boolean. When set to true, provide ACLs either in a global ACL configuration file ( aclConfigurationFilePath) or in per-document metadata files.
    
    aclConfigurationFilePath – The Amazon S3 URI of the global ACL configuration file. Type: String. Length: 1–1,024 characters. Optional. If you don’t provide a global ACL configuration file, define ACLs in per-document metadata files.
    
    defaultAccessType – The access behavior applied to Amazon S3 prefixes that are not listed in the ACL configuration. Type: String. The only supported value is ALLOW.
    metadataFilesPrefix – (Optional) The Amazon S3 prefix under which per-document metadata files are stored. Each metadata file describes a single source document and its indexable attributes. This is not the global ACL configuration file. For a single global ACL file, use accessControlConfiguration.aclConfigurationFilePath. Type: String. Length: 1–1,024 characters.
    - Google Drive ( type: GOOGLEDRIVEV3) – Requires connectionConfiguration with authType set to SERVICE_ACCOUNT. Supports dataEntityConfiguration with crawlMyDrive, crawlSharedWithMe, and crawlSharedDrives.
    - OneDrive ( type: ONEDRIVEV3) – Requires authType at the template root level set to TWO_LEGGED_OAUTH. Requires connectionConfiguration with tenantId in UUID format. Supports dataEntityConfiguration with crawlPersonalDrives and crawlSharedWithMe.
    - SharePoint ( type: SHAREPOINTV3) – Requires connectionConfiguration with tenantId in UUID format. Supports dataEntityConfiguration with siteUrls, crawlFiles, and crawlPages.
    - Web Crawler ( type: WEBCRAWLERV3) – Requires connectionConfiguration with seedUrls or siteMapUrls (mutually exclusive) and authType. Supports crawlConfiguration for crawl depth, rate limits, and scope. Supports filterConfiguration for file size limits and URL patterns. Valid values for authType: NO_AUTH, BASIC_AUTH, FORM, SAML.
    Enabling document-level access control for Amazon S3
    
    For an Amazon S3 ( S3V2) knowledge base, document-level access control is governed by two settings that must both be enabled:
    - In this template, set accessControlConfiguration.crawlAcl to true. Define ACLs either in a global ACL configuration file, referenced by accessControlConfiguration.aclConfigurationFilePath, or in per-document metadata files. To control access for prefixes that are not listed in the ACL file, you can also set accessControlConfiguration.defaultAccessType.
    - In the CreateKnowledgeBase or UpdateKnowledgeBase request, set the top-level AccessControlConfiguration.isACLEnabled to true.
Description (string) – A description for the knowledge base. If you don’t specify a description, the knowledge base is created without one.
Permissions (list) –
A list of resource permissions on the knowledge base. Each entry grants a specified Amazon QuickSight principal either owner or viewer access. If you don’t specify permissions, only the primary owner (if provided) receives owner access.
- (dict) –
  
  Permission for the resource.
  - Principal (string) – [REQUIRED]
    
    The Amazon Resource Name (ARN) of the principal. This can be one of the following:
    - The ARN of an Quick Sight user or group associated with a data source or dataset. (This is common.)
    - The ARN of an Quick Sight user, group, or namespace associated with an analysis, dashboard, template, or theme. Namespace sharing is not supported for action connectors. (This is common.)
    - The ARN of an Amazon Web Services account root: This is an IAM ARN rather than a Quick Sight ARN. Use this option only to share resources (templates) across Amazon Web Services accounts. Account root sharing is not supported for action connectors. (This is less common.)
  - Actions (list) – [REQUIRED]
    
    The IAM action to grant or revoke permissions on.
    - (string) –
MediaExtractionConfiguration (dict) –
The configuration for media extraction from knowledge base documents.
- imageExtractionConfiguration (dict) –
  
  The configuration for image extraction.
  - imageExtractionStatus (string) – [REQUIRED]
    
    The status of image extraction. Valid values are ENABLED and DISABLED.
- audioExtractionConfiguration (dict) –
  
  The configuration for audio extraction.
  - audioExtractionStatus (string) – [REQUIRED]
    
    The status of audio extraction. Valid values are ENABLED and DISABLED.
- videoExtractionConfiguration (dict) –
  
  The configuration for video extraction.
  - videoExtractionStatus (string) – [REQUIRED]
    
    The status of video extraction. Valid values are ENABLED and DISABLED.
  - videoExtractionType (string) –
    
    The type of video extraction to perform.
AccessControlConfiguration (dict) –
The access control configuration for the knowledge base. If you don’t specify this parameter, document-level ACLs are disabled.
- isACLEnabled (boolean) –
  
  Specifies whether ACLs are enabled for the knowledge base.
  
  This setting works together with the data source connector’s ACL crawling. To enforce document-level access control end to end, set isACLEnabled to true and enable ACL crawling on the connector. For example, for an Amazon S3 data source, set accessControlConfiguration.crawlAcl to true in the connector template. For more information, see KbTemplateConfiguration. Enabling only one of the two settings does not produce a fully ACL-enforced knowledge base.
PrimaryOwnerArn (string) –
The Amazon Resource Name (ARN) of the Amazon QuickSight user or group to set as the primary owner of the knowledge base. The specified principal is always granted owner access, regardless of what is specified in the Permissions field.

This must be an Amazon QuickSight principal ARN, not an IAM user or role ARN. The API caller is never assigned as the owner automatically. If you don’t specify a primary owner and don’t grant owner access in Permissions, the knowledge base is created without an owner, even when you call the operation as an Amazon QuickSight user.

When you call CreateKnowledgeBase as an IAM user or an assumed IAM role, specify PrimaryOwnerArn (as an Amazon QuickSight principal ARN) or an owner entry in Permissions so that the knowledge base has an owner. Although optional, specifying a primary owner is recommended.
Tags (list) –
The tags to assign to the knowledge base. If you don’t specify tags, the knowledge base is created without tags.
- (dict) –
  
  The key or keys of the key-value pairs for the resource tag or tags assigned to the resource.
  - Key (string) – [REQUIRED]
    
    Tag key.
  - Value (string) – [REQUIRED]
    
    Tag value.

Return type:

dict

Returns:

Response Syntax

{
    'KnowledgeBaseArn': 'string',
    'KnowledgeBaseId': 'string',
    'CreationStatus': 'CREATING'|'UPDATING'|'ACTIVE'|'FAILED'|'DELETING',
    'RequestId': 'string',
    'Status': 123
}

Response Structure

(dict) –
- KnowledgeBaseArn (string) –
  
  The Amazon Resource Name (ARN) of the knowledge base.
- KnowledgeBaseId (string) –
  
  The unique identifier for the knowledge base.
- CreationStatus (string) –
  
  The creation status of the knowledge base.
- RequestId (string) –
  
  The Amazon Web Services request ID for this operation.
- Status (integer) –
  
  The HTTP status of the request.

Exceptions

QuickSight.Client.exceptions.ResourceExistsException
QuickSight.Client.exceptions.ThrottlingException
QuickSight.Client.exceptions.InvalidRequestException
QuickSight.Client.exceptions.InvalidParameterValueException
QuickSight.Client.exceptions.InternalFailureException
QuickSight.Client.exceptions.PreconditionNotMetException
QuickSight.Client.exceptions.ResourceNotFoundException
QuickSight.Client.exceptions.LimitExceededException
QuickSight.Client.exceptions.AccessDeniedException