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'
            },
            'distribute': {
                'locations': [
                    {
                        '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, distribute.
  - 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.
  - distribute (dict) –
    
    Required configuration for a protected query with a distribute output type.
    - locations (list) – [REQUIRED]
      
      A list of locations where you want to distribute the protected query results. Each location must specify either an S3 destination or a collaboration member destination.
      
      Warning
      You can’t specify more than one S3 location.
      
      You can’t specify the query runner’s account as a member location.
      
      You must include either an S3 or member output configuration for each location, but not both.
      - (dict) –
        
        Specifies where you’ll distribute the results of your protected query. You must configure either an S3 destination or a collaboration member destination.
        
        Note
        This is a Tagged Union structure. Only one of the following top level keys can be set: s3, member.
        
        s3 (dict) –
        
        Contains the configuration to write the query results to S3.
        
        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) –
        
        Contains configuration details for the protected query member output.
        
        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'
                },
                'distribute': {
                    'locations': [
                        {
                            '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'
                    },
                ],
                'distribute': {
                    '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, distribute. 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.
      - distribute (dict) –
        
        Required configuration for a protected query with a distribute output type.
        
        locations (list) –
        
        A list of locations where you want to distribute the protected query results. Each location must specify either an S3 destination or a collaboration member destination.
        
        Warning
        You can’t specify more than one S3 location.
        
        You can’t specify the query runner’s account as a member location.
        
        You must include either an S3 or member output configuration for each location, but not both.
        
        (dict) –
        
        Specifies where you’ll distribute the results of your protected query. You must configure either an S3 destination or a collaboration member destination.
        
        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) –
        
        Contains the configuration to write the query results to S3.
        
        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) –
        
        Contains configuration details for the protected query member output.
        
        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, in milliseconds.
    - 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, distribute. 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.
      - distribute (dict) –
        
        Contains output information for protected queries that use a distribute output type. This output type lets you send query results to multiple locations - either to S3 or to collaboration members.
        
        Note
        You can only use the distribute output type with the Spark analytics engine.
        
        s3 (dict) –
        
        Contains output information for protected queries with an S3 output type.
        
        location (string) –
        
        The S3 location of the result.
        
        memberList (list) –
        
        Contains the output results for each member location specified in the distribute output configuration. Each entry provides details about the result distribution to a specific collaboration member.
        
        (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.

start_protected_query¶

Request Syntax

Note

Warning

Note

Note

Response Syntax

Response Structure

Note

Warning

Note

Note

Note

Note

Exceptions