Skip to content

Execute a statement

The /ksql resource runs a sequence of SQL statements. All statements, except those starting with SELECT, can be run on this endpoint. To run SELECT statements use the /query endpoint.

Note

If you use the SET or UNSET statements to assign query properties by using the REST API, the assignment is scoped only to the current request. In contrast, SET and UNSET assignments in the ksqlDB CLI persist throughout the CLI session.

POST /ksql

Run a sequence of SQL statements.

JSON Parameters:

  • ksql (string): A semicolon-delimited sequence of SQL statements to run.
  • streamsProperties (map): Property overrides to run the statements with. Refer to the :ref:Config Reference <ksql-param-reference> for details on properties that can be set.
  • streamsProperties[property-name] (string): The value of the property
  • named by property-name. Both the value and property-name should be strings.
  • commandSequenceNumber (long): Optional. If specified, the statements will not be run until all existing commands up to and including the specified sequence number have completed. If unspecified, the statements are run immediately. When a command is processed, the result object contains its sequence number.

The response JSON is an array of result objects. The result object contents depend on the statement that it is returning results for. The following sections detail the contents of the result objects by statement.

Common Fields

The following fields are common to all responses.

Response JSON Object:

  • statementText (string): The SQL statement whose result is being returned.
  • warnings (array): A list of warnings about conditions that may be unexpected by the user, but don't result in failure to execute the statement.
  • warnings[i].message (string): A message detailing the condition being warned on.

CREATE, DROP, TERMINATE

Response JSON Object:

  • commandId (string): A string that identifies the requested operation. You can use this ID to poll the result of the operation using the status endpoint.
  • commandStatus.status (string): One of QUEUED, PARSING, EXECUTING, TERMINATED, SUCCESS, or ERROR.
  • commandStatus.message (string): Detailed message regarding the status of the execution statement.
  • commandSequenceNumber (long): The sequence number of the requested operation in the command queue, or -1 if the operation was unsuccessful.

LIST STREAMS, SHOW STREAMS

Response JSON Object:

  • streams (array): List of streams.
  • streams[i].name (string): The name of the stream.
  • streams[i].topic (string): The topic backing the stream.
  • streams[i].format (string): The serialization format of the data in the stream. One of JSON, AVRO, PROTOBUF, or DELIMITED.
  • streams[i].type (string): The source type. Always returns STREAM.

LIST TABLES, SHOW TABLES

Response JSON Object:

  • tables (array): List of tables.
  • tables[i].name (string): The name of the table.
  • tables[i].topic (string): The topic backing the table.
  • tables[i].format (string): The serialization format of the data in the table. One of JSON, AVRO, PROTOBUF, or DELIMITED.
  • tables[i].type (string): The source type. Always returns TABLE.
  • tables[i].isWindowed (boolean): true if the table provides windowed results; otherwise, false.

LIST QUERIES, SHOW QUERIES

Response JSON Object:

  • queries (array): List of queries.
  • queries[i].queryString (string): The text of the statement that started the query.
  • queries[i].sinks (string): The streams and tables being written to by the query.
  • queries[i].id (string): The query ID.

LIST PROPERTIES, SHOW PROPERTIES

Response JSON Object:

  • properties (map): The ksqlDB server query properties.
  • properties[property-name] (string): The value of the property named by property-name.

DESCRIBE

Response JSON Object:

  • sourceDescription.name (string): The name of the stream or table.
  • sourceDescription.readQueries (array): The queries reading from the stream or table.
  • sourceDescription.writeQueries (array): The queries writing into the stream or table
  • sourceDescription.fields (array): A list of field objects that describes each field in the stream/table.
  • sourceDescription.fields[i].name (string): The name of the field.
  • sourceDescription.fields[i].schema (object): A schema object that describes the schema of the field.
  • sourceDescription.fields[i].schema.type (string): The type the schema represents. One of INTEGER, BIGINT, BOOLEAN, DOUBLE, STRING, MAP, ARRAY, or STRUCT.
  • sourceDescription.fields[i].schema.memberSchema (object): A schema object. For MAP and ARRAY types, contains the schema of the map values and array elements, respectively. For other types this field is not used and its value is undefined.
  • sourceDescription.fields[i].schema.fields (array): For STRUCT types, contains a list of field objects that describes each field within the struct. For other types this field is not used and its value is undefined.
  • sourceDescription.type (string): STREAM or TABLE
  • sourceDescription.key (string): The name of the key column.
  • sourceDescription.timestamp (string): The name of the timestamp column.
  • sourceDescription.format (string): The serialization format of the data in the stream or table. One of JSON, AVRO, PROTOBUF, or DELIMITED.
  • sourceDescription.topic (string): The topic backing the stream or table.
  • sourceDescription.extended (boolean): A boolean that indicates whether this is an extended description.
  • sourceDescription.statistics (string): A string that contains statistics about production and consumption to and from the backing topic (extended only).
  • sourceDescription.errorStats (string): A string that contains statistics about errors producing and consuming to and from the backing topic (extended only).
  • sourceDescription.replication (int): The replication factor of the backing topic (extended only).
  • sourceDescription.partitions (int): The number of partitions in the backing topic (extended only).

EXPLAIN

Response JSON Object:

  • queryDescription.statementText (string): The ksqlDB statement for which the query being explained is running.
  • queryDescription.fields (array): A list of field objects that describes each field in the query output.
  • queryDescription.fields[i].name (string): The name of the field.
  • queryDescription.fields[i].schema (object): A schema object that describes the schema of the field.
  • queryDescription.fields[i].schema.type (string): The type the schema represents. One of INTEGER, BIGINT, BOOLEAN, DOUBLE, STRING, MAP, ARRAY, or STRUCT.
  • queryDescription.fields[i].schema.memberSchema (object): A schema object. For MAP and ARRAY types, contains the schema of the map values and array elements, respectively. For other types this field is not used and its value is undefined.
  • queryDescription.fields[i].schema.fields (array): For STRUCT types, contains a list of field objects that descrbies each field within the struct. For other types this field is not used and its value is undefined.
  • queryDescription.sources (array): The streams and tables being read by the query.
  • queryDescription.sources[i] (string): The name of a stream or table being read from by the query.
  • queryDescription.sinks (array): The streams and tables being written to by the query.
  • queryDescription.sinks[i] (string): The name of a stream or table being written to by the query.
  • queryDescription.executionPlan (string): They query execution plan.
  • queryDescription.topology (string): The Kafka Streams topology that the query is running.
  • overriddenProperties (map): The property overrides that the query is running with.

Errors

If ksqlDB fails to execute a statement, it returns a response with an error status code (4xx/5xx). Even if an error is returned, the server may have been able to successfully execute some statements in the request. In this case, the response includes the error_code and message fields, a statementText field with the text of the failed statement, and an entities field that contains an array of result objects:

Response JSON Object:

  • statementText (string): The text of the SQL statement where the error occurred.
  • entities (array): Result objects for statements that were successfully executed by the server.

The /ksql endpoint may return the following error codes in the error_code field:

  • 40001 (BAD_STATEMENT): The request contained an invalid SQL statement.
  • 40002 (QUERY_ENDPOINT): The request contained a statement that should be issued to the /query endpoint.

Example request

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
POST /ksql HTTP/1.1
Accept: application/vnd.ksql.v1+json
Content-Type: application/vnd.ksql.v1+json

{
  "ksql": "CREATE STREAM pageviews_home AS SELECT * FROM pageviews_original WHERE pageid='home'; CREATE STREAM pageviews_alice AS SELECT * FROM pageviews_original WHERE userid='alice';",
  "streamsProperties": {
    "ksql.streams.auto.offset.reset": "earliest"
  }
}

Example response

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
HTTP/1.1 200 OK
Content-Type: application/vnd.ksql.v1+json

[
  {
    "statementText":"CREATE STREAM pageviews_home AS SELECT * FROM pageviews_original WHERE pageid='home';",
    "commandId":"stream/PAGEVIEWS_HOME/create",
    "commandStatus": {
      "status":"SUCCESS",
      "message":"Stream created and running"
    },
    "commandSequenceNumber":10
  },
  {
    "statementText":"CREATE STREAM pageviews_alice AS SELECT * FROM pageviews_original WHERE userid='alice';",
    "commandId":"stream/PAGEVIEWS_ALICE/create",
    "commandStatus": {
      "status":"SUCCESS",
      "message":"Stream created and running"
    },
    "commandSequenceNumber":11
  }
]

Coordinate Multiple Requests

To submit multiple, interdependent requests, there are two options. The first is to submit them as a single request, similar to the example request above:

1
2
3
4
5
6
7
POST /ksql HTTP/1.1
Accept: application/vnd.ksql.v1+json
Content-Type: application/vnd.ksql.v1+json

{
  "ksql": "CREATE STREAM pageviews_home AS SELECT * FROM pageviews_original WHERE pageid='home'; CREATE TABLE pageviews_home_count AS SELECT userid, COUNT(*) FROM pageviews_home GROUP BY userid EMIT CHANGES;"
}

The second method is to submit the statements as separate requests and incorporate the interdependency by using commandSequenceNumber. Send the first request:

1
2
3
4
5
6
7
POST /ksql HTTP/1.1
Accept: application/vnd.ksql.v1+json
Content-Type: application/vnd.ksql.v1+json

{
  "ksql": "CREATE STREAM pageviews_home AS SELECT * FROM pageviews_original WHERE pageid='home' EMIT CHANGES;"
}

Make note of the commandSequenceNumber returned in the response:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
HTTP/1.1 200 OK
Content-Type: application/vnd.ksql.v1+json

[
  {
    "statementText":"CREATE STREAM pageviews_home AS SELECT * FROM pageviews_original WHERE pageid='home' EMIT CHANGES;",
    "commandId":"stream/PAGEVIEWS_HOME/create",
    "commandStatus": {
      "status":"SUCCESS",
      "message":"Stream created and running"
    },
    "commandSequenceNumber":10
  }
]

Provide this commandSequenceNumber as part of the second request, indicating that this request should not execute until after command number 10 has finished executing:

1
2
3
4
5
6
7
8
POST /ksql HTTP/1.1
Accept: application/vnd.ksql.v1+json
Content-Type: application/vnd.ksql.v1+json

{
  "ksql": "CREATE TABLE pageviews_home_count AS SELECT userid, COUNT(*) FROM pageviews_home GROUP BY userid EMIT CHANGES;",
  "commandSequenceNumber":10
}

Page last revised on: 2020-05-06

Last update: 2020-05-06