:doc:`RedshiftDataAPIService <../../redshift-data>` / Client / execute_statement

*****************
execute_statement
*****************



.. py:method:: RedshiftDataAPIService.Client.execute_statement(**kwargs)

  

  Runs an SQL statement, which can be data manipulation language (DML) or data definition language (DDL). This statement must be a single SQL statement. Depending on the authorization method, use one of the following combinations of request parameters:

   

  
  * Secrets Manager - when connecting to a cluster, provide the ``secret-arn`` of a secret stored in Secrets Manager which has ``username`` and ``password``. The specified secret contains credentials to connect to the ``database`` you specify. When you are connecting to a cluster, you also supply the database name, If you provide a cluster identifier ( ``dbClusterIdentifier``), it must match the cluster identifier stored in the secret. When you are connecting to a serverless workgroup, you also supply the database name.
   
  * Temporary credentials - when connecting to your data warehouse, choose one of the following options: 

    
    * When connecting to a serverless workgroup, specify the workgroup name and database name. The database user name is derived from the IAM identity. For example, ``arn:iam::123456789012:user:foo`` has the database user name ``IAM:foo``. Also, permission to call the ``redshift-serverless:GetCredentials`` operation is required.
     
    * When connecting to a cluster as an IAM identity, specify the cluster identifier and the database name. The database user name is derived from the IAM identity. For example, ``arn:iam::123456789012:user:foo`` has the database user name ``IAM:foo``. Also, permission to call the ``redshift:GetClusterCredentialsWithIAM`` operation is required.
     
    * When connecting to a cluster as a database user, specify the cluster identifier, the database name, and the database user name. Also, permission to call the ``redshift:GetClusterCredentials`` operation is required.
    

  
  

   

  For more information about the Amazon Redshift Data API and CLI usage examples, see `Using the Amazon Redshift Data API <https://docs.aws.amazon.com/redshift/latest/mgmt/data-api.html>`__ in the *Amazon Redshift Management Guide*.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/redshift-data-2019-12-20/ExecuteStatement>`_  


  **Request Syntax**
  ::

    response = client.execute_statement(
        Sql='string',
        ClusterIdentifier='string',
        SecretArn='string',
        DbUser='string',
        Database='string',
        WithEvent=True|False,
        StatementName='string',
        Parameters=[
            {
                'name': 'string',
                'value': 'string'
            },
        ],
        WorkgroupName='string',
        ClientToken='string',
        ResultFormat='JSON'|'CSV',
        SessionKeepAliveSeconds=123,
        SessionId='string'
    )
    
  :type Sql: string
  :param Sql: **[REQUIRED]** 

    The SQL statement text to run.

    

  
  :type ClusterIdentifier: string
  :param ClusterIdentifier: 

    The cluster identifier. This parameter is required when connecting to a cluster and authenticating using either Secrets Manager or temporary credentials.

    

  
  :type SecretArn: string
  :param SecretArn: 

    The name or ARN of the secret that enables access to the database. This parameter is required when authenticating using Secrets Manager.

    

  
  :type DbUser: string
  :param DbUser: 

    The database user name. This parameter is required when connecting to a cluster as a database user and authenticating using temporary credentials.

    

  
  :type Database: string
  :param Database: 

    The name of the database. This parameter is required when authenticating using either Secrets Manager or temporary credentials.

    

  
  :type WithEvent: boolean
  :param WithEvent: 

    A value that indicates whether to send an event to the Amazon EventBridge event bus after the SQL statement runs.

    

  
  :type StatementName: string
  :param StatementName: 

    The name of the SQL statement. You can name the SQL statement when you create it to identify the query.

    

  
  :type Parameters: list
  :param Parameters: 

    The parameters for the SQL statement.

    

  
    - *(dict) --* 

      A parameter used in a SQL statement.

      

    
      - **name** *(string) --* **[REQUIRED]** 

        The name of the parameter.

        

      
      - **value** *(string) --* **[REQUIRED]** 

        The value of the parameter. Amazon Redshift implicitly converts to the proper data type. For more information, see `Data types <https://docs.aws.amazon.com/redshift/latest/dg/c_Supported_data_types.html>`__ in the *Amazon Redshift Database Developer Guide*.

        

      
    

  :type WorkgroupName: string
  :param WorkgroupName: 

    The serverless workgroup name or Amazon Resource Name (ARN). This parameter is required when connecting to a serverless workgroup and authenticating using either Secrets Manager or temporary credentials.

    

  
  :type ClientToken: string
  :param ClientToken: 

    A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.

    This field is autopopulated if not provided.

  
  :type ResultFormat: string
  :param ResultFormat: 

    The data format of the result of the SQL statement. If no format is specified, the default is JSON.

    

  
  :type SessionKeepAliveSeconds: integer
  :param SessionKeepAliveSeconds: 

    The number of seconds to keep the session alive after the query finishes. The maximum time a session can keep alive is 24 hours. After 24 hours, the session is forced closed and the query is terminated.

    

  
  :type SessionId: string
  :param SessionId: 

    The session identifier of the query.

    

  
  
  :rtype: dict
  :returns: 
    
    **Response Syntax**

    
    ::

      {
          'Id': 'string',
          'CreatedAt': datetime(2015, 1, 1),
          'ClusterIdentifier': 'string',
          'DbUser': 'string',
          'DbGroups': [
              'string',
          ],
          'Database': 'string',
          'SecretArn': 'string',
          'WorkgroupName': 'string',
          'SessionId': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **Id** *(string) --* 

        The identifier of the SQL statement whose results are to be fetched. This value is a universally unique identifier (UUID) generated by Amazon Redshift Data API.

        
      

      - **CreatedAt** *(datetime) --* 

        The date and time (UTC) the statement was created.

        
      

      - **ClusterIdentifier** *(string) --* 

        The cluster identifier. This element is not returned when connecting to a serverless workgroup.

        
      

      - **DbUser** *(string) --* 

        The database user name.

        
      

      - **DbGroups** *(list) --* 

        A list of colon (:) separated names of database groups.

        
        

        - *(string) --* 
    
      

      - **Database** *(string) --* 

        The name of the database.

        
      

      - **SecretArn** *(string) --* 

        The name or ARN of the secret that enables access to the database.

        
      

      - **WorkgroupName** *(string) --* 

        The serverless workgroup name or Amazon Resource Name (ARN). This element is not returned when connecting to a provisioned cluster.

        
      

      - **SessionId** *(string) --* 

        The session identifier of the query.

        
  
  **Exceptions**
  
  *   :py:class:`RedshiftDataAPIService.Client.exceptions.ValidationException`

  
  *   :py:class:`RedshiftDataAPIService.Client.exceptions.ActiveSessionsExceededException`

  
  *   :py:class:`RedshiftDataAPIService.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`RedshiftDataAPIService.Client.exceptions.ExecuteStatementException`

  
  *   :py:class:`RedshiftDataAPIService.Client.exceptions.ActiveStatementsExceededException`

  
  *   :py:class:`RedshiftDataAPIService.Client.exceptions.InternalServerException`

  