CleanRoomsService / Client / start_protected_query

start_protected_query#

CleanRoomsService.Client.start_protected_query(**kwargs)#

Creates a protected query that is started by Clean Rooms.

Request Syntax

response = client.start_protected_query(
    type='SQL',
    membershipIdentifier='string',
    sqlParameters={
        'queryString': 'string',
        'analysisTemplateArn': 'string',
        'parameters': {
            'string': 'string'
        }
    },
    resultConfiguration={
        'outputConfiguration': {
            's3': {
                'resultFormat': 'CSV'|'PARQUET',
                'bucket': 'string',
                'keyPrefix': 'string',
                'singleFileOutput': True|False
            },
            'member': {
                'accountId': 'string'
            }
        }
    },
    computeConfiguration={
        'worker': {
            'type': 'CR.1X'|'CR.4X',
            'number': 123
        }
    }
)

Parameters:

type (string) –
[REQUIRED]

The type of the protected query to be started.
membershipIdentifier (string) –
[REQUIRED]

A unique identifier for the membership to run this query against. Currently accepts a membership ID.
sqlParameters (dict) –
[REQUIRED]

The protected SQL query parameters.
- queryString (string) –
  
  The query string to be submitted.
- analysisTemplateArn (string) –
  
  The Amazon Resource Name (ARN) associated with the analysis template within a collaboration.
- parameters (dict) –
  
  The protected query SQL parameters.
  - (string) –
    - (string) –
resultConfiguration (dict) –
The details needed to write the query results.
- outputConfiguration (dict) – [REQUIRED]
  
  Configuration for protected query results.
  
  Note
  This is a Tagged Union structure. Only one of the following top level keys can be set: s3, member.
  - s3 (dict) –
    
    Required configuration for a protected query with an s3 output type.
    - resultFormat (string) – [REQUIRED]
      
      Intended file format of the result.
    - bucket (string) – [REQUIRED]
      
      The S3 bucket to unload the protected query results.
    - keyPrefix (string) –
      
      The S3 prefix to unload the protected query results.
    - singleFileOutput (boolean) –
      
      Indicates whether files should be output as a single file ( TRUE) or output as multiple files ( FALSE). This parameter is only supported for analyses with the Spark analytics engine.
  - member (dict) –
    
    Required configuration for a protected query with a member output type.
    - accountId (string) – [REQUIRED]
      
      The unique identifier for the account.
computeConfiguration (dict) –
The compute configuration for the protected query.

Note
This is a Tagged Union structure. Only one of the following top level keys can be set: worker.
- worker (dict) –
  
  The worker configuration for the compute environment.
  - type (string) –
    
    The worker compute configuration type.
  - number (integer) –
    
    The number of workers.

Return type:

dict

Returns:

Response Syntax

{
    'protectedQuery': {
        'id': 'string',
        'membershipId': 'string',
        'membershipArn': 'string',
        'createTime': datetime(2015, 1, 1),
        'sqlParameters': {
            'queryString': 'string',
            'analysisTemplateArn': 'string',
            'parameters': {
                'string': 'string'
            }
        },
        'status': 'SUBMITTED'|'STARTED'|'CANCELLED'|'CANCELLING'|'FAILED'|'SUCCESS'|'TIMED_OUT',
        'resultConfiguration': {
            'outputConfiguration': {
                's3': {
                    'resultFormat': 'CSV'|'PARQUET',
                    'bucket': 'string',
                    'keyPrefix': 'string',
                    'singleFileOutput': True|False
                },
                'member': {
                    'accountId': 'string'
                }
            }
        },
        'statistics': {
            'totalDurationInMillis': 123,
            'billedResourceUtilization': {
                'units': 123.0
            }
        },
        'result': {
            'output': {
                's3': {
                    'location': 'string'
                },
                'memberList': [
                    {
                        'accountId': 'string'
                    },
                ]
            }
        },
        'error': {
            'message': 'string',
            'code': 'string'
        },
        'differentialPrivacy': {
            'sensitivityParameters': [
                {
                    'aggregationType': 'AVG'|'COUNT'|'COUNT_DISTINCT'|'SUM'|'STDDEV',
                    'aggregationExpression': 'string',
                    'userContributionLimit': 123,
                    'minColumnValue': ...,
                    'maxColumnValue': ...
                },
            ]
        },
        'computeConfiguration': {
            'worker': {
                'type': 'CR.1X'|'CR.4X',
                'number': 123
            }
        }
    }
}

Response Structure

(dict) –
- protectedQuery (dict) –
  
  The protected query.
  - id (string) –
    
    The identifier for a protected query instance.
  - membershipId (string) –
    
    The identifier for the membership.
  - membershipArn (string) –
    
    The ARN of the membership.
  - createTime (datetime) –
    
    The time at which the protected query was created.
  - sqlParameters (dict) –
    
    The protected query SQL parameters.
    - queryString (string) –
      
      The query string to be submitted.
    - analysisTemplateArn (string) –
      
      The Amazon Resource Name (ARN) associated with the analysis template within a collaboration.
    - parameters (dict) –
      
      The protected query SQL parameters.
      - (string) –
        
        (string) –
  - status (string) –
    
    The status of the query.
  - resultConfiguration (dict) –
    
    Contains any details needed to write the query results.
    - outputConfiguration (dict) –
      
      Configuration for protected query results.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: s3, member. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - s3 (dict) –
        
        Required configuration for a protected query with an s3 output type.
        
        resultFormat (string) –
        
        Intended file format of the result.
        
        bucket (string) –
        
        The S3 bucket to unload the protected query results.
        
        keyPrefix (string) –
        
        The S3 prefix to unload the protected query results.
        
        singleFileOutput (boolean) –
        
        Indicates whether files should be output as a single file ( TRUE) or output as multiple files ( FALSE). This parameter is only supported for analyses with the Spark analytics engine.
      - member (dict) –
        
        Required configuration for a protected query with a member output type.
        
        accountId (string) –
        
        The unique identifier for the account.
  - statistics (dict) –
    
    Statistics about protected query execution.
    - totalDurationInMillis (integer) –
      
      The duration of the protected query, from creation until query completion.
    - billedResourceUtilization (dict) –
      
      The billed resource utilization.
      - units (float) –
        
        The number of Clean Rooms Processing Unit (CRPU) hours that have been billed.
  - result (dict) –
    
    The result of the protected query.
    - output (dict) –
      
      The output of the protected query.
      Note
      This is a Tagged Union structure. Only one of the following top level keys will be set: s3, memberList. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
      
      'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
      - s3 (dict) –
        
        If present, the output for a protected query with an S3 output type.
        
        location (string) –
        
        The S3 location of the result.
      - memberList (list) –
        
        The list of member Amazon Web Services account(s) that received the results of the query.
        
        (dict) –
        
        Details about the member who received the query result.
        
        accountId (string) –
        
        The Amazon Web Services account ID of the member in the collaboration who can receive results for the query.
  - error (dict) –
    
    An error thrown by the protected query.
    - message (string) –
      
      A description of why the query failed.
    - code (string) –
      
      An error code for the error.
  - differentialPrivacy (dict) –
    
    The sensitivity parameters of the differential privacy results of the protected query.
    - sensitivityParameters (list) –
      
      Provides the sensitivity parameters that you can use to better understand the total amount of noise in query results.
      - (dict) –
        
        Provides the sensitivity parameters.
        
        aggregationType (string) –
        
        The type of aggregation function that was run.
        
        aggregationExpression (string) –
        
        The aggregation expression that was run.
        
        userContributionLimit (integer) –
        
        The maximum number of rows contributed by a user in a SQL query.
        
        minColumnValue (float) –
        
        The lower bound of the aggregation expression.
        
        maxColumnValue (float) –
        
        The upper bound of the aggregation expression.
  - computeConfiguration (dict) –
    
    The compute configuration for the protected query.
    Note
    This is a Tagged Union structure. Only one of the following top level keys will be set: worker. If a client receives an unknown member it will set SDK_UNKNOWN_MEMBER as the top level key, which maps to the name or tag of the unknown member. The structure of SDK_UNKNOWN_MEMBER is as follows:
    'SDK_UNKNOWN_MEMBER': {'name': 'UnknownMemberName'}
    - worker (dict) –
      
      The worker configuration for the compute environment.
      - type (string) –
        
        The worker compute configuration type.
      - number (integer) –
        
        The number of workers.

Exceptions

CleanRoomsService.Client.exceptions.ServiceQuotaExceededException
CleanRoomsService.Client.exceptions.ResourceNotFoundException
CleanRoomsService.Client.exceptions.InternalServerException
CleanRoomsService.Client.exceptions.ValidationException
CleanRoomsService.Client.exceptions.ThrottlingException
CleanRoomsService.Client.exceptions.AccessDeniedException