:doc:`Kinesis <../../kinesis>` / Client / put_records

***********
put_records
***********



.. py:method:: Kinesis.Client.put_records(**kwargs)

  

  Writes multiple data records into a Kinesis data stream in a single call (also referred to as a ``PutRecords`` request). Use this operation to send data into the stream for data ingestion and processing.

   

  .. note::

    

    When invoking this API, you must use either the ``StreamARN`` or the ``StreamName`` parameter, or both. It is recommended that you use the ``StreamARN`` input parameter when you invoke this API.

    

   

  Each ``PutRecords`` request can support up to 500 records. Each record in the request can be as large as 10 MiB, up to a limit of 10 MiB for the entire request, including partition keys. Each shard can support writes up to 1,000 records per second, up to a maximum data write total of 1 MB per second.

   

  You must specify the name of the stream that captures, stores, and transports the data; and an array of request ``Records``, with each record in the array requiring a partition key and data blob. The record size limit applies to the total size of the partition key and data blob.

   

  The data blob can be any type of data; for example, a segment from a log file, geographic/location data, website clickstream data, and so on.

   

  The partition key is used by Kinesis Data Streams as input to a hash function that maps the partition key and associated data to a specific shard. An MD5 hash function is used to map partition keys to 128-bit integer values and to map associated data records to shards. As a result of this hashing mechanism, all data records with the same partition key map to the same shard within the stream. For more information, see `Adding Data to a Stream <https://docs.aws.amazon.com/kinesis/latest/dev/developing-producers-with-sdk.html#kinesis-using-sdk-java-add-data-to-stream>`__ in the *Amazon Kinesis Data Streams Developer Guide*.

   

  Each record in the ``Records`` array may include an optional parameter, ``ExplicitHashKey``, which overrides the partition key to shard mapping. This parameter allows a data producer to determine explicitly the shard where the record is stored. For more information, see `Adding Multiple Records with PutRecords <https://docs.aws.amazon.com/kinesis/latest/dev/developing-producers-with-sdk.html#kinesis-using-sdk-java-putrecords>`__ in the *Amazon Kinesis Data Streams Developer Guide*.

   

  The ``PutRecords`` response includes an array of response ``Records``. Each record in the response array directly correlates with a record in the request array using natural ordering, from the top to the bottom of the request and response. The response ``Records`` array always includes the same number of records as the request array.

   

  The response ``Records`` array includes both successfully and unsuccessfully processed records. Kinesis Data Streams attempts to process all records in each ``PutRecords`` request. A single record failure does not stop the processing of subsequent records. As a result, PutRecords doesn't guarantee the ordering of records. If you need to read records in the same order they are written to the stream, use  PutRecord instead of ``PutRecords``, and write to the same shard.

   

  A successfully processed record includes ``ShardId`` and ``SequenceNumber`` values. The ``ShardId`` parameter identifies the shard in the stream where the record is stored. The ``SequenceNumber`` parameter is an identifier assigned to the put record, unique to all records in the stream.

   

  An unsuccessfully processed record includes ``ErrorCode`` and ``ErrorMessage`` values. ``ErrorCode`` reflects the type of error and can be one of the following values: ``ProvisionedThroughputExceededException`` or ``InternalFailure``. ``ErrorMessage`` provides more detailed information about the ``ProvisionedThroughputExceededException`` exception including the account ID, stream name, and shard ID of the record that was throttled. For more information about partially successful responses, see `Adding Multiple Records with PutRecords <https://docs.aws.amazon.com/kinesis/latest/dev/kinesis-using-sdk-java-add-data-to-stream.html#kinesis-using-sdk-java-putrecords>`__ in the *Amazon Kinesis Data Streams Developer Guide*.

   

  .. warning::

     

    After you write a record to a stream, you cannot modify that record or its order within the stream.

     

   

  By default, data records are accessible for 24 hours from the time that they are added to a stream. You can use  IncreaseStreamRetentionPeriod or  DecreaseStreamRetentionPeriod to modify this retention period.

  

  See also: `AWS API Documentation <https://docs.aws.amazon.com/goto/WebAPI/kinesis-2013-12-02/PutRecords>`_  


  **Request Syntax**
  ::

    response = client.put_records(
        Records=[
            {
                'Data': b'bytes',
                'ExplicitHashKey': 'string',
                'PartitionKey': 'string'
            },
        ],
        StreamName='string',
        StreamARN='string',
        StreamId='string'
    )
    
  :type Records: list
  :param Records: **[REQUIRED]** 

    The records associated with the request.

    

  
    - *(dict) --* 

      Represents the output for ``PutRecords``.

      

    
      - **Data** *(bytes) --* **[REQUIRED]** 

        The data blob to put into the record, which is base64-encoded when the blob is serialized. When the data blob (the payload before base64-encoding) is added to the partition key size, the total size must not exceed the maximum record size (10 MiB).

        

      
      - **ExplicitHashKey** *(string) --* 

        The hash value used to determine explicitly the shard that the data record is assigned to by overriding the partition key hash.

        

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

        Determines which shard in the stream the data record is assigned to. Partition keys are Unicode strings with a maximum length limit of 256 characters for each key. Amazon Kinesis Data Streams uses the partition key as input to a hash function that maps the partition key and associated data to a specific shard. Specifically, an MD5 hash function is used to map partition keys to 128-bit integer values and to map associated data records to shards. As a result of this hashing mechanism, all data records with the same partition key map to the same shard within the stream.

        

      
    

  :type StreamName: string
  :param StreamName: 

    The stream name associated with the request.

    

  
  :type StreamARN: string
  :param StreamARN: 

    The ARN of the stream.

    

  
  :type StreamId: string
  :param StreamId: 

    Not Implemented. Reserved for future use.

    

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

    
    ::

      {
          'FailedRecordCount': 123,
          'Records': [
              {
                  'SequenceNumber': 'string',
                  'ShardId': 'string',
                  'ErrorCode': 'string',
                  'ErrorMessage': 'string'
              },
          ],
          'EncryptionType': 'NONE'|'KMS'
      }
      
    **Response Structure**

    

    - *(dict) --* 

      ``PutRecords`` results.

      
      

      - **FailedRecordCount** *(integer) --* 

        The number of unsuccessfully processed records in a ``PutRecords`` request.

        
      

      - **Records** *(list) --* 

        An array of successfully and unsuccessfully processed record results. A record that is successfully added to a stream includes ``SequenceNumber`` and ``ShardId`` in the result. A record that fails to be added to a stream includes ``ErrorCode`` and ``ErrorMessage`` in the result.

        
        

        - *(dict) --* 

          Represents the result of an individual record from a ``PutRecords`` request. A record that is successfully added to a stream includes ``SequenceNumber`` and ``ShardId`` in the result. A record that fails to be added to the stream includes ``ErrorCode`` and ``ErrorMessage`` in the result.

          
          

          - **SequenceNumber** *(string) --* 

            The sequence number for an individual record result.

            
          

          - **ShardId** *(string) --* 

            The shard ID for an individual record result.

            
          

          - **ErrorCode** *(string) --* 

            The error code for an individual record result. ``ErrorCodes`` can be either ``ProvisionedThroughputExceededException`` or ``InternalFailure``.

            
          

          - **ErrorMessage** *(string) --* 

            The error message for an individual record result. An ``ErrorCode`` value of ``ProvisionedThroughputExceededException`` has an error message that includes the account ID, stream name, and shard ID. An ``ErrorCode`` value of ``InternalFailure`` has the error message ``"Internal Service Failure"``.

            
      
    
      

      - **EncryptionType** *(string) --* 

        The encryption type used on the records. This parameter can be one of the following values:

         

        
        * ``NONE``: Do not encrypt the records.
         
        * ``KMS``: Use server-side encryption on the records using a customer-managed Amazon Web Services KMS key.
        

        
  
  **Exceptions**
  
  *   :py:class:`Kinesis.Client.exceptions.ResourceNotFoundException`

  
  *   :py:class:`Kinesis.Client.exceptions.InvalidArgumentException`

  
  *   :py:class:`Kinesis.Client.exceptions.ProvisionedThroughputExceededException`

  
  *   :py:class:`Kinesis.Client.exceptions.KMSDisabledException`

  
  *   :py:class:`Kinesis.Client.exceptions.KMSInvalidStateException`

  
  *   :py:class:`Kinesis.Client.exceptions.KMSAccessDeniedException`

  
  *   :py:class:`Kinesis.Client.exceptions.KMSNotFoundException`

  
  *   :py:class:`Kinesis.Client.exceptions.KMSOptInRequired`

  
  *   :py:class:`Kinesis.Client.exceptions.KMSThrottlingException`

  
  *   :py:class:`Kinesis.Client.exceptions.AccessDeniedException`

  
  *   :py:class:`Kinesis.Client.exceptions.InternalFailureException`

  