# exec * *Endpoint URL* /api/v2/exec * *HTTP Method* POST * *Description * Executes a SQL statement without returning result sets; typically used for executing DDL and DML statements for which result sets are not expected, such as `CREATE TABLE` and `INSERT` statements. ## Request Headers | Header | Description | | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Authorization | Specifies the authentication information of the user agent. For more information, see[Data API Authentication](https://docs.singlestore.com/cloud/reference/data-api/data-api-authentication.md). | | Content-Type | Represents the media type (MIME) of the body of the request and must be set to`application/json`. | ## Request Body The request body is a JSON object that specifies the SQL statement to execute and the statement context. The request body size must not exceed 1MB. | Field | Type | Description | | -------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | sql | String | The SQL statement to execute. | | args | Array | (Optional) A list of arguments to be used in the SQL statement. The command uses question marks (?) for placeholders, which will be replaced by the specified arguments during execution. The command must have exactly as many placeholders as arguments, or the request will fail.*Example*:`{"sql": "INSERT INTO tbl (col1, col2) VALUES (?, ?)", "args": ["Hello", 2]}` | | args\[x] | Any | (Optional) An argument to be used in the command. This argument will be parsed into a Golang type based on the default JSON parsing rules and then passed to the go sql driver for safe interpolation. | | database | String | (Optional) The database on which the SQL statement must be executed. | ## Response For successful requests, the response will be a JSON object in the message body along with the HTTP status code *200 OK*. | Field | Type | Description | | ------------ | ------- | ----------------------------------------------------------------------------------------- | | lastInsertId | Integer | The last value inserted into an`AUTO_INCREMENT`column if applicable to the SQL statement. | | rowsAffected | Integer | The number of rows affected by the SQL statement. | On request failure, an HTTP status code corresponding to the error will be returned. See [Data API Error Handling](https://docs.singlestore.com/cloud/reference/data-api/data-api-error-handling.md) for more information. ## Examples (Shell) ## Create a database ## Request Data ```json {"sql": "CREATE DATABASE publications"} ``` ## HTTP Request ```shell curl -H "Content-Type: application/json" --data '{"sql": "CREATE DATABASE publications"}' https://svc-10444e3f-afeb-46be-b186-a8c64b99f726-dml.aws-ireland-1.svc.singlestore.com/api/v2/exec ``` ## HTTP Response ```json { "lastInsertId": 0, "rowsAffected": 1 } ``` ## Create a table ## Request Data ```json {"sql": "CREATE TABLE authors(author_id INT AUTO_INCREMENT PRIMARY KEY, author_name VARCHAR(50) NOT NULL, bio VARCHAR(255))", "database": "publications"} ``` ## HTTP Request ```shell curl -H "Content-Type: application/json" --data '{"sql": "CREATE TABLE authors(author_id INT AUTO_INCREMENT PRIMARY KEY, author_name VARCHAR(50) NOT NULL, bio VARCHAR(255))", "database": "publications"}' https://svc-10444e3f-afeb-46be-b186-a8c64b99f726-dml.aws-ireland-1.svc.singlestore.com/api/v2/exec ``` ## HTTP Response ```json { "lastInsertId": 0, "rowsAffected": 0 } ``` ## Insert values into a table ## Request Data ```json {"sql": "INSERT INTO authors (author_name) VALUES (?), (?), (?)", "args": ["Kegan Roslyn", "Toby Lynsey", "Lacey Desmond"], "database": "publications"} ``` ## HTTP Request ```shell curl -H "Content-Type: application/json" --data '{"sql": "INSERT INTO authors (author_name) VALUES (?), (?), (?)", "args": ["Kegan Roslyn", "Toby Lynsey", "Lacey Desmond"], "database": "publications"}' https://svc-10444e3f-afeb-46be-b186-a8c64b99f726-dml.aws-ireland-1.svc.singlestore.com/api/v2/exec ``` ## HTTP Response ```json { "lastInsertId": 1, "rowsAffected": 3 } ``` ## Call a stored procedure ## Request Data ```json {"sql": "CALL sample_procedure(?)", "args": ["Crime Thriller"], "database": "publications"} ``` ## HTTP Request ```shell curl -H "Content-Type: application/json" --data '{"sql": "CALL sample_procedure(?)", "args": ["Crime Thriller"], "database": "publications"}' https://svc-10444e3f-afeb-46be-b186-a8c64b99f726-dml.aws-ireland-1.svc.singlestore.com/api/v2/exec ``` ## HTTP Response ```json { "lastInsertId": 0, "rowsAffected": 0 } ``` ## Set an engine variable ## Request Data ```json {"sql": "SET GLOBAL data_conversion_compatibility_level = '8.0'"} ``` ## HTTP Request ```shell curl -H "Content-Type: application/json" --data '{"sql": "SET GLOBAL data_conversion_compatibility_level = '\''8.0'\''"}' https://admin:pa55w0rd@svc-XXXX-dml.aws-oregon-4.svc.singlestore.com/api/v2/exec ``` ## HTTP Response ```json { "lastInsertId": 0, "rowsAffected": 0 } ``` ## Supplementary Reference When using cURL to invoke SingleStore’s Data API, you can issue the JSON payload of the HTTP POST request from a file instead of providing it directly in the request, as shown below. ## Create a table by issuing HTTP POST request’s JSON payload from a file ## Request data saved in a JSON file ```json { "sql": "CREATE TABLE reviews(book_title VARCHAR(255) NOT NULL, author_name VARCHAR(50), review JSON NOT NULL)", "database": "publications" } ``` ## HTTP request with the JSON payload issued from the JSON file ```shell #/* The JSON payload for the HTTP request is supplied from the exec.json file */ curl -H "Content-Type: application/json" --data '@./exec.json' https://svc-10444e3f-afeb-46be-b186-a8c64b99f726-dml.aws-ireland-1.svc.singlestore.com/api/v2/exec ``` ## HTTP response ```json { "lastInsertId": 0, "rowsAffected": 0 } ``` *** Modified at: August 8, 2023 Source: [/cloud/reference/data-api/data-api-endpoint-reference/exec/](https://docs.singlestore.com/cloud/reference/data-api/data-api-endpoint-reference/exec/) (An index of the documentation is available at /llms.txt)