@Rocky how to run a query on http 8030 port from python?

Starting with version 3.2.0, StarRocks provides an HTTP SQL API that allows you to run queries via the FE's HTTP port (default 8030). Basic Syntax To run a query, send a

POST

request to the

/api/v1/catalogs/<catalog_name>/databases/<database_name>/sql

endpoint.

bash
curl -X POST 'http://<FE_IP>:8030/api/v1/catalogs/default_catalog/databases/<your_db>/sql' \
     -u '<username>:<password>' \
     -H 'Content-Type: application/json' \
     -d '{"query": "SELECT * FROM <your_table> LIMIT 10;"}'

Key Details * Authentication: Uses Basic Auth. If no password is set, use

-u 'username:'

. * Supported Statements:

SELECT

,

SHOW

,

EXPLAIN

, and

KILL

. * Request Body: *

query

(Required): The SQL string to execute. *

sessionVariables

(Optional): A JSON object of session variables to apply (e.g.,

{"query_timeout": 60}

). * Response Format: Returns data in Newline delimited JSON (

application/x-ndjson

). Each line is a separate JSON object containing

connectionId

,

meta

(column info),

data

(row data), or

statistics

. * Catalog Scope: * In v3.2.0, only

default_catalog

(internal tables) is supported. * Starting from v3.2.1, you can also query external catalogs. Examples 1. Querying without specifying a database in the URL: If you don't specify the database in the path, you must use the fully qualified table name (

db.table

) in your SQL:

bash
curl -X POST '<http://127.0.0.1:8030/api/v1/catalogs/default_catalog/sql>' \
     -u 'root:' \
     -d '{"query": "SELECT * FROM test_db.my_table;"}'

2. Setting session variables:

bash
curl -X POST '<http://127.0.0.1:8030/api/v1/catalogs/default_catalog/databases/test_db/sql>' \
     -u 'root:' \
     -d '{
       "query": "SELECT count(*) FROM my_table;",
       "sessionVariables": {"pipeline_dop": 8}
     }'

For versions earlier than 3.2.0, there is no official REST API for general SQL execution; you would typically use the MySQL protocol (port 9030) via a MySQL client or JDBC/JDBC/JDBC driver. References • sql-reference/http_sql_api.md • administration/http_interface.md

@Rocky from python

To run a query on port 8030 (StarRocks HTTP SQL API) using Python, you can use the

requests

library. Since the API returns data in Newline Delimited JSON (ndjson) format, you should iterate over the response lines. Example Code This requires StarRocks v3.2.0 or later.

python
import requests
import json

# Configuration
fe_host = "127.0.0.1"
fe_port = 8030
catalog = "default_catalog"
database = "your_db"
username = "root"
password = ""  # Leave empty if no password

url = f"http://{fe_host}:{fe_port}/api/v1/catalogs/{catalog}/databases/{database}/sql"

payload = {
    "query": "SELECT * FROM your_table LIMIT 5;",
    "sessionVariables": {"query_timeout": 60}
}

try:
    # Use stream=True because the response is ndjson (multiple JSON objects)
    response = <http://requests.post|requests.post>(
        url, 
        auth=(username, password), 
        json=payload, 
        stream=True
    )
    
    if response.status_code == 200:
        for line in response.iter_lines():
            if line:
                row = json.loads(line)
                
                # The response objects can be: connectionId, meta, data, or statistics
                if "data" in row:
                    print(f"Row: {row['data']}")
                elif "meta" in row:
                    print(f"Columns: {[col['name'] for col in row['meta']]}")
                elif "statistics" in row:
                    print(f"Stats: {row['statistics']}")
    else:
        print(f"Error {response.status_code}: {response.text}")

except Exception as e:
    print(f"Connection failed: {e}")

Key Considerations 1. Response Format: The API streams data. Each line is a separate JSON object. * `{"connectionId": ...}`: The first line returned. * `{"meta": [...]}`: Describes column names and types. * `{"data": [...]}`: One line per row of data. * `{"statistics": ...}`: The final summary. 2. Authentication: Uses Basic Auth. If your root user has no password, pass

password=""

(the

requests

library handles the header construction). 3. Port: Port 8030 is the default

http_port

. If you intended to use a standard database driver (like

mysql-connector-python

or

sqlalchemy

), you should use the MySQL protocol port (default 9030) instead. References • sql-reference/http_sql_api.md • administration/http_interface.md References • sql-reference/http_sql_api.md • administration/http_interface.md