CreateStream

On This Page

Description

Creates and configures a new stream. The configuration includes the stream’s shard count and retention period. The new stream is available immediately upon its creation.

Request

Request Header

Syntax

    POST /<container>/<resource> HTTP/1.1
    Host: <web-APIs URL>
    Content-Type: application/json
    X-v3io-function: CreateStream
    <Authorization OR X-v3io-session-key>: <value>

    url = "http://<web-APIs URL>/<container>/<resource>"
    headers = {
                "Content-Type": "application/json",
                "X-v3io-function": "CreateStream",
                "<Authorization OR X-v3io-session-key>": "<value>"
              }

    URL Resource Parameters

    The path to the new stream. You can optionally set the stream name in the request’s StreamName JSON parameter instead of in the URL.

    Request Data

    Syntax

      {
          "StreamName":           "string",
          "ShardCount":           number,
          "RetentionPeriodHours": number
      }

      payload = {
                  "StreamName":           "string",
                  "ShardCount":           number,
                  "RetentionPeriodHours": number
                }

      Parameters
      StreamName
      A unique name for the new stream (collection) that will be created.

      • Type: String
      • Requirement: Required if not set in the request URL
      ShardCount
      The steam’s shard count, i.e., the number of stream shards to create.

      • Type: Number
      • Requirement: Required
      • Valid Values: A positive integer (>= 1). For example, 100.
      • Default Value: 1
      RetentionPeriodHours
      The stream’s retention period, in hours. After this period elapses, when new records are added to the stream, the earliest ingested records are deleted.

      • Type: Number
      • Requirement: Required
      • Valid Values: A positive integer (>= 1). For example, 2 (2 hours).
      • Default Value: 24 (1 day)

      Response

      Response Data

      None

      Errors

      In the event of an error, the response includes a JSON object with an ErrorCode element that contains a unique numeric error code, and an ErrorMessage element that contains one of the following API error messages:
      Error Message Description
      InvalidArgumentException A provided request parameter is not valid for this request.
      Permission denied The sender of the request does not have the required permissions to perform the operation.
      ResourceInUseException A collection already exists in the specified stream path.

      Examples

      Create a stream named mycontainer with 1000 shards and a retention period of one hour:

      Request

        POST /mycontainer/MyStream/ HTTP/1.1
        Host: https://default-tenant.app.mycluster.iguazio.com:8443
        Content-Type: application/json
        X-v3io-function: CreateStream
        X-v3io-session-key: e8bd4ca2-537b-4175-bf01-8c74963e90bf
        {
            "ShardCount":           1000,
            "RetentionPeriodHours": 1
        }

        import requests
        
        url = "https://default-tenant.app.mycluster.iguazio.com:8443/mycontainer/MyStream/"
        headers = {
                    "Content-Type": "application/json",
                    "X-v3io-function": "CreateStream",
                    "X-v3io-session-key": "e8bd4ca2-537b-4175-bf01-8c74963e90bf"
                  }
        payload = {"ShardCount": 1000, "RetentionPeriodHours": 1}
        
        response = requests.post(url, json=payload, headers=headers)
        print(response.text)

        Response
        HTTP/1.1 200 OK
        Content-Type: application/json