CleanRoomsService / Client / start_protected_query

start_protected_query

CleanRoomsService.Client.start_protected_query(**kwargs)

Creates a protected query that is started by Clean Rooms.

See also: AWS API Documentation

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.

Exceptions