:doc:`Personalize <../../personalize>` / Client / create_batch_inference_job

**************************
create_batch_inference_job
**************************



.. py:method:: Personalize.Client.create_batch_inference_job(**kwargs)

  

  Generates batch recommendations based on a list of items or users stored in Amazon S3 and exports the recommendations to an Amazon S3 bucket.

   

  To generate batch recommendations, specify the ARN of a solution version and an Amazon S3 URI for the input and output data. For user personalization, popular items, and personalized ranking solutions, the batch inference job generates a list of recommended items for each user ID in the input file. For related items solutions, the job generates a list of recommended items for each item ID in the input file.

   

  For more information, see `Creating a batch inference job <https://docs.aws.amazon.com/personalize/latest/dg/getting-batch-recommendations.html>`__.

   

  If you use the Similar-Items recipe, Amazon Personalize can add descriptive themes to batch recommendations. To generate themes, set the job's mode to ``THEME_GENERATION`` and specify the name of the field that contains item names in the input data.

   

  For more information about generating themes, see `Batch recommendations with themes from Content Generator <https://docs.aws.amazon.com/personalize/latest/dg/themed-batch-recommendations.html>`__.

   

  You can't get batch recommendations with the Trending-Now or Next-Best-Action recipes.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/personalize-2018-05-22/CreateBatchInferenceJob>`_  


  **Request Syntax**
  ::

    response = client.create_batch_inference_job(
        jobName='string',
        solutionVersionArn='string',
        filterArn='string',
        numResults=123,
        jobInput={
            's3DataSource': {
                'path': 'string',
                'kmsKeyArn': 'string'
            }
        },
        jobOutput={
            's3DataDestination': {
                'path': 'string',
                'kmsKeyArn': 'string'
            }
        },
        roleArn='string',
        batchInferenceJobConfig={
            'itemExplorationConfig': {
                'string': 'string'
            },
            'rankingInfluence': {
                'string': 123.0
            }
        },
        tags=[
            {
                'tagKey': 'string',
                'tagValue': 'string'
            },
        ],
        batchInferenceJobMode='BATCH_INFERENCE'|'THEME_GENERATION',
        themeGenerationConfig={
            'fieldsForThemeGeneration': {
                'itemName': 'string'
            }
        }
    )
    
  :type jobName: string
  :param jobName: **[REQUIRED]** 

    The name of the batch inference job to create.

    

  
  :type solutionVersionArn: string
  :param solutionVersionArn: **[REQUIRED]** 

    The Amazon Resource Name (ARN) of the solution version that will be used to generate the batch inference recommendations.

    

  
  :type filterArn: string
  :param filterArn: 

    The ARN of the filter to apply to the batch inference job. For more information on using filters, see `Filtering batch recommendations <https://docs.aws.amazon.com/personalize/latest/dg/filter-batch.html>`__.

    

  
  :type numResults: integer
  :param numResults: 

    The number of recommendations to retrieve.

    

  
  :type jobInput: dict
  :param jobInput: **[REQUIRED]** 

    The Amazon S3 path that leads to the input file to base your recommendations on. The input material must be in JSON format.

    

  
    - **s3DataSource** *(dict) --* **[REQUIRED]** 

      The URI of the Amazon S3 location that contains your input data. The Amazon S3 bucket must be in the same region as the API endpoint you are calling.

      

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

        The file path of the Amazon S3 bucket.

        

      
      - **kmsKeyArn** *(string) --* 

        The Amazon Resource Name (ARN) of the Key Management Service (KMS) key that Amazon Personalize uses to encrypt or decrypt the input and output files.

        

      
    
  
  :type jobOutput: dict
  :param jobOutput: **[REQUIRED]** 

    The path to the Amazon S3 bucket where the job's output will be stored.

    

  
    - **s3DataDestination** *(dict) --* **[REQUIRED]** 

      Information on the Amazon S3 bucket in which the batch inference job's output is stored.

      

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

        The file path of the Amazon S3 bucket.

        

      
      - **kmsKeyArn** *(string) --* 

        The Amazon Resource Name (ARN) of the Key Management Service (KMS) key that Amazon Personalize uses to encrypt or decrypt the input and output files.

        

      
    
  
  :type roleArn: string
  :param roleArn: **[REQUIRED]** 

    The ARN of the Amazon Identity and Access Management role that has permissions to read and write to your input and output Amazon S3 buckets respectively.

    

  
  :type batchInferenceJobConfig: dict
  :param batchInferenceJobConfig: 

    The configuration details of a batch inference job.

    

  
    - **itemExplorationConfig** *(dict) --* 

      A string to string map specifying the exploration configuration hyperparameters, including ``explorationWeight`` and ``explorationItemAgeCutOff``, you want to use to configure the amount of item exploration Amazon Personalize uses when recommending items. See `User-Personalization <https://docs.aws.amazon.com/personalize/latest/dg/native-recipe-new-item-USER_PERSONALIZATION.html>`__.

      

    
      - *(string) --* 

      
        - *(string) --* 

        
  

    - **rankingInfluence** *(dict) --* 

      A map of ranking influence values for POPULARITY and FRESHNESS. For each key, specify a numerical value between 0.0 and 1.0 that determines how much influence that ranking factor has on the final recommendations. A value closer to 1.0 gives more weight to the factor, while a value closer to 0.0 reduces its influence.

      

    
      - *(string) --* 

      
        - *(float) --* 

        
  

  
  :type tags: list
  :param tags: 

    A list of `tags <https://docs.aws.amazon.com/personalize/latest/dg/tagging-resources.html>`__ to apply to the batch inference job.

    

  
    - *(dict) --* 

      The optional metadata that you apply to resources to help you categorize and organize them. Each tag consists of a key and an optional value, both of which you define. For more information see `Tagging Amazon Personalize resources <https://docs.aws.amazon.com/personalize/latest/dg/tagging-resources.html>`__.

      

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

        One part of a key-value pair that makes up a tag. A key is a general label that acts like a category for more specific tag values.

        

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

        The optional part of a key-value pair that makes up a tag. A value acts as a descriptor within a tag category (key).

        

      
    

  :type batchInferenceJobMode: string
  :param batchInferenceJobMode: 

    The mode of the batch inference job. To generate descriptive themes for groups of similar items, set the job mode to ``THEME_GENERATION``. If you don't want to generate themes, use the default ``BATCH_INFERENCE``.

     

    When you get batch recommendations with themes, you will incur additional costs. For more information, see `Amazon Personalize pricing <https://aws.amazon.com/personalize/pricing/>`__.

    

  
  :type themeGenerationConfig: dict
  :param themeGenerationConfig: 

    For theme generation jobs, specify the name of the column in your Items dataset that contains each item's name.

    

  
    - **fieldsForThemeGeneration** *(dict) --* **[REQUIRED]** 

      Fields used to generate descriptive themes for a batch inference job.

      

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

        The name of the Items dataset column that stores the name of each item in the dataset.

        

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

    
    ::

      {
          'batchInferenceJobArn': 'string'
      }
      
    **Response Structure**

    

    - *(dict) --* 
      

      - **batchInferenceJobArn** *(string) --* 

        The ARN of the batch inference job.

        
  
  **Exceptions**
  
  *   :py:class:`Personalize.Client.exceptions.InvalidInputException`

  
  *   :py:class:`Personalize.Client.exceptions.ResourceAlreadyExistsException`

  
  *   :py:class:`Personalize.Client.exceptions.LimitExceededException`

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

  
  *   :py:class:`Personalize.Client.exceptions.ResourceInUseException`

  
  *   :py:class:`Personalize.Client.exceptions.TooManyTagsException`

  