### Pinot Hybrid Quickstart Cluster Setup

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Starts a Pinot hybrid quickstart cluster using Docker.

```bash
docker run --name pinot-quickstart \
  -p 2123:2123 -p 9000:9000 -p 8000:8000 \
  -d apachepinot/pinot:latest QuickStart -type hybrid
```

--------------------------------

### Install pinotdb

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/getting-started.md

Install the pinotdb package from PyPI.

```bash
pip install pinotdb
```

--------------------------------

### Pinot Hybrid Quickstart Example Execution

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Runs the Pinot hybrid quickstart example script.

```bash
python3 examples/pinot_quickstart_hybrid.py
```

--------------------------------

### Pinot Batch Quickstart Example Execution

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Runs the Pinot batch quickstart example script.

```bash
python3 examples/pinot_quickstart_batch.py
```

--------------------------------

### Start Pinot cluster with Docker

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/getting-started.md

Start a Pinot cluster using Docker for quick local testing.

```bash
docker run --name pinot-quickstart \
  -p 2123:2123 -p 9000:9000 -p 8000:8000 \
  -d apachepinot/pinot:latest QuickStart -type batch
```

--------------------------------

### Install pinotdb with SQLAlchemy support

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/getting-started.md

Install the pinotdb package with optional SQLAlchemy support.

```bash
pip install pinotdb[sqlalchemy]
```

--------------------------------

### Pinot Batch Quickstart Sample Output

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Sample output from running the Pinot batch quickstart example.

```text
Sending SQL to Pinot: SELECT * FROM baseballStats LIMIT 5
[0, 11, 0, 0, 0, 0, 0, 0, 0, 0, 'NL', 11, 11, 'aardsda01', 'David Allan', ...]

Sending SQL to Pinot: SELECT playerName, sum(runs) FROM baseballStats
    WHERE yearID>=2000 GROUP BY playerName LIMIT 5
['Scott Michael', 26.0]
['Justin Morgan', 0.0]
...

Sending SQL to Pinot: SELECT playerName,sum(runs) AS sum_runs FROM baseballStats
    WHERE yearID>=2000 GROUP BY playerName ORDER BY sum_runs DESC LIMIT 5
['Adrian', 1820.0]
['Jose Antonio', 1692.0]
['Rafael', 1565.0]
...
```

--------------------------------

### Start Pinot quickstart (Docker)

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/AGENTS.md

Starts a Pinot quickstart container using Make.

```bash
make run-pinot
```

--------------------------------

### Setup

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/contributing.md

Commands to clone the repository and install dependencies.

```bash
# Clone the repository
git clone https://github.com/startreedata/pinot-dbapi.git
cd pinot-dbapi

# Install dependencies
make init
```

--------------------------------

### Quick Start with SQLAlchemy

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/getting-started.md

Connect to a Pinot cluster using SQLAlchemy and execute a SQL query.

```python
from sqlalchemy import create_engine, text

engine = create_engine(
    'pinot://localhost:8099/query/sql?controller=http://localhost:9000/'
)

with engine.connect() as connection:
    result = connection.execute(text("SELECT count(*) FROM baseballStats"))
    print(result.scalar())
```

--------------------------------

### Query Options Example

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Example of configuring query parameters using `connect_args`.

```python
engine = create_engine(
    "pinot://localhost:8000/query/sql?controller=http://localhost:9000/",
    connect_args={
        "query_options": "use_multistage_engine=true;timeoutMs=10000"
    }
)

```

--------------------------------

### Quick Start with DB-API

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/getting-started.md

Connect to a Pinot cluster using the DB-API interface and execute a SQL query.

```python
from pinotdb import connect

conn = connect(host='localhost', port=8000, path='/query/sql', scheme='http')
curs = conn.cursor()
curs.execute("SELECT * FROM baseballStats LIMIT 5")
for row in curs:
    print(row)
```

--------------------------------

### Async Support Example

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Example of using `create_async_engine` for asyncio support.

```python
from sqlalchemy import text
from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine(
    "pinot+async://localhost:8000/query/sql?controller=http://localhost:9000/"
)

async with engine.connect() as connection:
    result = await connection.execute(
        text("SELECT * FROM baseballStats LIMIT 5")
    )
    print(result.fetchall())

```

--------------------------------

### Authentication Example

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Example of creating a SQLAlchemy engine with authentication credentials.

```python
engine = create_engine(
    'pinot+https://my-user:my-password@my-secure-broker:443/query/sql'
    '?controller=https://my-secure-controller/&&verify_ssl=true'
)

```

--------------------------------

### Async Queries Example Execution

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Runs the example demonstrating async query execution.

```bash
python3 examples/pinot_async.py
```

--------------------------------

### Multi-Stage Engine Example Execution

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Runs the example demonstrating Pinot's multi-stage query engine.

```bash
python3 examples/pinot_quickstart_multi_stage.py
```

--------------------------------

### Pinot Batch Quickstart Docker Command

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Command to start the Pinot Batch Quickstart environment using Docker.

```bash
docker run --name pinot-quickstart -p 2123:2123 -p 9000:9000 -p 8000:8000 -d apachepinot/pinot:latest QuickStart -type batch
```

--------------------------------

### Pinot Hybrid Quickstart Docker Command

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Command to start the Pinot Hybrid Quickstart environment using Docker.

```bash
docker run --name pinot-quickstart -p 2123:2123 -p 9000:9000 -p 8000:8000 -d apachepinot/pinot:latest QuickStart -type hybrid
```

--------------------------------

### Quick Example

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/index.md

Connect to Pinot and execute a query.

```python
from pinotdb import connect

conn = connect(host='localhost', port=8000, path='/query/sql', scheme='http')
curs = conn.cursor()
curs.execute("SELECT * FROM myTable LIMIT 10")
for row in curs:
    print(row)
```

--------------------------------

### HTTPS Async Support Example

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Example of creating an async engine for HTTPS connections.

```python
engine = create_async_engine(
    "pinot+https_async://localhost:443/query/sql"
    "?controller=https://localhost:9000/"
)

```

--------------------------------

### Authentication with Zookeeper Example Execution

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Runs the example demonstrating connecting to a Pinot cluster with authentication and Zookeeper-based broker discovery.

```bash
python3 examples/pinot_quickstart_auth_zk.py
```

--------------------------------

### Pinot Live Demo Example Execution

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Runs the example that connects to the public Pinot live demo cluster.

```bash
python3 examples/pinot_live.py
```

--------------------------------

### JSON Index Queries Example Execution

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Runs the example showing how to query JSON-indexed columns in Pinot.

```bash
python3 examples/pinot_quickstart_json_batch.py
```

--------------------------------

### Query Timeout Example Execution

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/examples.md

Runs the example showing how to configure query timeout options.

```bash
python3 examples/pinot_quickstart_timeout.py
```

--------------------------------

### HTTPS Basic Usage Example

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Example of creating a SQLAlchemy engine for an HTTPS connection.

```python
engine = create_engine(
    'pinot+https://pinot-broker.pinot.live:443/query/sql'
    '?controller=https://pinot-controller.pinot.live/'
)

```

--------------------------------

### Basic Usage

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Example of creating a SQLAlchemy engine and querying a Pinot table.

```python
from sqlalchemy import *
from sqlalchemy.engine import create_engine
from sqlalchemy.schema import *

engine = create_engine(
    'pinot://localhost:8099/query/sql?controller=http://localhost:9000/'
)

metadata = MetaData()
places = Table('places', metadata, autoload_with=engine)
query = select(func.count()).select_from(places)

with engine.connect() as connection:
    print(connection.execute(query).scalar())

```

--------------------------------

### Multi-Stage Engine Enablement

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Example of enabling the multi-stage query engine via `connect_args`.

```python
engine = create_engine(
    "pinot://localhost:8000/query/sql?controller=http://localhost:9000/",
    connect_args={"use_multistage_engine": "true"}
)

```

--------------------------------

### Pinot Hybrid Quickstart Sample Output

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Sample output from querying the Pinot Hybrid Quickstart.

```text
Sending SQL to Pinot: SELECT * FROM airlineStats LIMIT 5
[171, 153, 19393, 0, 8, 8, 1433, '1400-1459', 0, 1425, 1240, 165, 'null', 0, 'WN', -2147483648, 1, 27, 17540, 0, 2, 2, 1242, '1200-1259', 0, 'MDW', 13232, 1323202, 30977, 'Chicago, IL', 'IL', 17, 'Illinois', 41, 861, 4, -2147483648, [-2147483648], 0, [-2147483648], ['null'], -2147483648, -2147483648, [-2147483648], -2147483648, ['null'], [-2147483648], [-2147483648], [-2147483648], 0, -2147483648, '2014-01-27', 402, 1, -2147483648, -2147483648, 1, -2147483648, 'BOS', 10721, 1072102, 30721, 'Boston, MA', 'MA', 25, 'Massachusetts', 13, 1, ['null'], -2147483648, 'N556WN', 6, 12, -2147483648, 'WN', -2147483648, 1254, 1427, 2014]
[183, 141, 20398, 1, 17, 17, 1302, '1200-1259', 1, 1245, 1005, 160, 'null', 0, 'MQ', 0, 1, 27, 17540, 0, -6, 0, 959, '1000-1059', -1, 'CMH', 11066, 1106603, 31066, 'Columbus, OH', 'OH', 39, 'Ohio', 44, 990, 4, -2147483648, [-2147483648], 0, [-2147483648], ['null'], -2147483648, -2147483648, [-2147483648], -2147483648, ['null'], [-2147483648], [-2147483648], [-2147483648], 0, -2147483648, '2014-01-27', 3574, 1, 0, -2147483648, 1, 17, 'MIA', 13303, 1330303, 32467, 'Miami, FL', 'FL', 12, 'Florida', 33, 1, ['null'], 0, 'N605MQ', 13, 29, -2147483648, 'MQ', 0, 1028, 1249, 2014]
[-2147483648, -2147483648, 20304, -2147483648, -2147483648, -2147483648, -2147483648, '2100-2159', -2147483648, 2131, 2005, 146, 'null', 0, 'OO', -2147483648, 1, 27, 17541, 1, 52, 52, 2057, '2000-2059', 3, 'COS', 11109, 1110902, 30189, 'Colorado Springs, CO', 'CO', 8, 'Colorado', 82, 809, 4, -2147483648, [11292], 1, [1129202], ['DEN'], -2147483648, 73, [9], 0, ['null'], [9], [-2147483648], [2304], 1, -2147483648, '2014-01-27', 5554, 1, -2147483648, -2147483648, 1, -2147483648, 'IAH', 12266, 1226603, 31453, 'Houston, TX', 'TX', 48, 'Texas', 74, 1, ['SEA', 'PSC', 'PHX', 'MSY', 'ATL', 'TYS', 'DEN', 'CHS', 'PDX', 'LAX', 'EWR', 'SFO', 'PIT', 'RDU', 'RAP', 'LSE', 'SAN', 'SBN', 'IAH', 'OAK', 'BRO', 'JFK', 'SAT', 'ORD', 'ACY', 'DFW', 'BWI'], -2147483648, 'N795SK', -2147483648, 19, -2147483648, 'OO', -2147483648, 2116, -2147483648, 2014]
[153, 125, 20436, 1, 41, 41, 1442, '1400-1459', 2, 1401, 1035, 146, 'null', 0, 'F9', 2, 1, 27, 17541, 1, 34, 34, 1109, '1000-1059', 2, 'DEN', 11292, 1129202, 30325, 'Denver, CO', 'CO', 8, 'Colorado', 82, 967, 4, -2147483648, [-2147483648], 0, [-2147483648], ['null'], -2147483648, -2147483648, [-2147483648], -2147483648, ['null'], [-2147483648], [-2147483648], [-2147483648], 0, -2147483648, '2014-01-27', 658, 1, 8, -2147483648, 1, 31, 'SFO', 14771, 1477101, 32457, 'San Francisco, CA', 'CA', 6, 'California', 91, 1, ['null'], 0, 'N923FR', 11, 17, -2147483648, 'F9', 0, 1126, 1431, 2014]
```

--------------------------------

### Pinot Batch Quickstart Sample Output

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Sample output from querying the Pinot Batch Quickstart.

```text
Sending SQL to Pinot: SELECT * FROM baseballStats LIMIT 5
[0, 11, 0, 0, 0, 0, 0, 0, 0, 0, 'NL', 11, 11, 'aardsda01', 'David Allan', 1, 0, 0, 0, 0, 0, 0, 'SFN', 0, 2004]
[2, 45, 0, 0, 0, 0, 0, 0, 0, 0, 'NL', 45, 43, 'aardsda01', 'David Allan', 1, 0, 0, 0, 1, 0, 0, 'CHN', 0, 2006]
[0, 2, 0, 0, 0, 0, 0, 0, 0, 0, 'AL', 25, 2, 'aardsda01', 'David Allan', 1, 0, 0, 0, 0, 0, 0, 'CHA', 0, 2007]
[1, 5, 0, 0, 0, 0, 0, 0, 0, 0, 'AL', 47, 5, 'aardsda01', 'David Allan', 1, 0, 0, 0, 0, 0, 1, 'BOS', 0, 2008]
[0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 'AL', 73, 3, 'aardsda01', 'David Allan', 1, 0, 0, 0, 0, 0, 0, 'SEA', 0, 2009]

Sending SQL to Pinot: SELECT playerName, sum(runs) FROM baseballStats WHERE yearID>=2000 GROUP BY playerName LIMIT 5
['Scott Michael', 26.0]
['Justin Morgan', 0.0]
['Jason Andre', 0.0]
['Jeffrey Ellis', 0.0]
['Maximiliano R.', 16.0]

Sending SQL to Pinot: SELECT playerName,sum(runs) AS sum_runs FROM baseballStats WHERE yearID>=2000 GROUP BY playerName ORDER BY sum_runs DESC LIMIT 5
['Adrian', 1820.0]
['Jose Antonio', 1692.0]
['Rafael', 1565.0]
['Brian Michael', 1500.0]
['Alexander Emmanuel', 1426.0]
```

--------------------------------

### Install dependencies (dev + extras)

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/AGENTS.md

Installs development dependencies and extras using Make.

```bash
make init
```

--------------------------------

### Authentication

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/db-api.md

Demonstrates how to establish a connection with basic authentication credentials.

```python
conn = connect(
    host="localhost",
    port=443,
    path="/query/sql",
    scheme="https",
    username="my-user",
    password="my-password",
    verify_ssl=True
)
```

--------------------------------

### Integration Tests

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/contributing.md

Commands to start Pinot and run integration tests.

```bash
# Start Pinot (in a separate terminal)
make run-pinot

# Run integration tests
make test-integration
```

--------------------------------

### Query Options

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/db-api.md

Shows how to pass additional query parameters to the execute method.

```python
curs.execute(
    "SELECT * FROM airlineStats LIMIT 10",
    queryOptions="useMultistageEngine=true"
)
```

--------------------------------

### Querying pinot.live demo cluster

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

This example demonstrates how to query the pinot.live demo cluster using the pinot-dbapi library, showing both direct connection and SQLAlchemy usage, along with the expected SQL query and response.

```bash
python3 examples/pinot_live.py
```

```text
Sending SQL to Pinot: SELECT * FROM airlineStats LIMIT 5
[384, 359, 19805, 0, 13, 13, 1238, '1200-1259', 0, 1225, 900, 385, 'null', 0, 'AA', -2147483648, 3, 1, 16071, 0, 14, 14, 914, '0900-0959', 0, 'LAX', 12892, 1289203, 32575, 'Los Angeles, CA', 'CA', 6, 'California', 91, 2475, 10, -2147483648, [-2147483648], 0, [-2147483648], ['null'], -2147483648, -2147483648, [-2147483648], -2147483648, ['null'], [-2147483648], [-2147483648], [-2147483648], 0, -2147483648, '2014-01-01', 1, 1, -2147483648, -2147483648, 1, -2147483648, 'JFK', 12478, 1247802, 31703, 'New York, NY', 'NY', 36, 'New York', 22, 1, ['SEA', 'PSC', 'PHX', 'MSY', 'ATL', 'TYS', 'DEN', 'CHS', 'PDX', 'LAX', 'EWR', 'SFO', 'PIT', 'RDU', 'RAP', 'LSE', 'SAN', 'SBN', 'IAH', 'OAK', 'BRO', 'JFK', 'SAT', 'ORD', 'ACY', 'DFW', 'BWI', 'TPA', 'BFL', 'BOS', 'SNA', 'ISN'], -2147483648, 'N338AA', 5, 20, -2147483648, 'AA', -2147483648, 934, 1233, 2014]
[269, 251, 19805, 0, -36, 0, 1549, '1600-1659', -2, 1625, 825, 300, 'null', 0, 'AA', -2147483648, 3, 1, 16071, 0, -5, 0, 820, '0800-0859', -1, 'JFK', 12478, 1247802, 31703, 'New York, NY', 'NY', 36, 'New York', 22, 2248, 9, -2147483648, [-2147483648], 0, [-2147483648], ['null'], -2147483648, -2147483648, [-2147483648], -2147483648, ['null'], [-2147483648], [-2147483648], [-2147483648], 0, -2147483648, '2014-01-01', 44, 1, -2147483648, -2147483648, 1, -2147483648, 'LAS', 12889, 1288903, 32211, 'Las Vegas, NV', 'NV', 32, 'Nevada', 85, 1, ['SEA', 'PSC', 'PHX', 'MSY', 'ATL', 'TYS', 'DEN', 'CHS', 'PDX', 'LAX', 'EWR', 'SFO', 'PIT', 'RDU', 'RAP', 'LSE', 'SAN', 'SBN', 'IAH', 'OAK'], -2147483648, 'N3DVAA', 6, 12, -2147483648, 'AA', -2147483648, 832, 1543, 2014]
[307, 288, 19805, 0, -26, 0, 2039, '2100-2159', -2, 2105, 1340, 325, 'null', 0, 'AA', -2147483648, 3, 1, 16071, 0, -8, 0, 1332, '1300-1359', -1, 'LAX', 12892, 1289203, 32575, 'Los Angeles, CA', 'CA', 6, 'California', 91, 2556, 11, -2147483648, [-2147483648], 0, [-2147483648], ['null'], -2147483648, -2147483648, [-2147483648], -2147483648, ['null'], [-2147483648], [-2147483648], [-2147483648], 0, -2147483648, '2014-01-01', 162, 1, -2147483648, -2147483648, 1, -2147483648, 'HNL', 12173, 1217301, 32134, 'Honolulu, HI', 'HI', 15, 'Hawaii', 2, 1, ['SEA', 'PSC', 'PHX', 'MSY', 'ATL', 'TYS', 'DEN'], -2147483648, 'N5FCAA', 8, 11, -2147483648, 'AA', -2147483648, 1343, 2031, 2014]
[141, 126, 19805, 0, -19, 0, 1456, '1500-1559', -2, 1515, 1135, 160, 'null', 0, 'AA', -2147483648, 3, 1, 16071, 0, 0, 0, 1135, '1100-1159', 0, 'DCA', 11278, 1127802, 30852, 'Washington, DC', 'VA', 51, 'Virginia', 38, 1192, 5, -2147483648, [-2147483648], 0, [-2147483648], ['null'], -2147483648, -2147483648, [-2147483648], -2147483648, ['null'], [-2147483648], [-2147483648], [-2147483648], 0, -2147483648, '2014-01-01', 130, 1, -2147483648, -2147483648, 1, -2147483648, 'DFW', 11298, 1129803, 30194, 'Dallas/Fort Worth, TX', 'TX', 48, 'Texas', 74, 1, ['null'], -2147483648, 'N3EGAA', 4, 11, -2147483648, 'AA', -2147483648, 1146, 1452, 2014]
[300, 277, 19805, 0, -8, 0, 32, '0001-0559', -1, 40, 1625, 315, 'null', 0, 'AA', -2147483648, 3, 1, 16071, 0, 7, 7, 1632, '1600-1659', 0, 'JFK', 12478, 1247802, 31703, 'New York, NY', 'NY', 36, 'New York', 22, 2475, 10, -2147483648, [-2147483648], 0, [-2147483648], ['null'], -2147483648, -2147483648, [-2147483648], -2147483648, ['null'], [-2147483648], [-2147483648], [-2147483648], 0, -2147483648, '2014-01-01', 180, 1, -2147483648, -2147483648, 1, -2147483648, 'LAX', 12892, 1289203, 32575, 'Los Angeles, CA', 'CA', 6, 'California', 91, 1, ['null'], -2147483648, 'N335AA', 10, 13, -2147483648, 'AA', -2147483648, 1645, 22, 2014]

Sending Count(*) SQL to Pinot
9746

Sending SQL: "SELECT playerName, sum(runs) AS sum_runs FROM "baseballStats" WHERE yearID>=2000 GROUP BY playerName ORDER BY sum_runs DESC LIMIT 5" to Pinot
[(19790, 581.0), (19977, 522.0), (19690, 520.0), (19805, 481.0), (20409, 410.0), (21171, 385.0), (19930, 378.0), (20355, 377.0), (19393, 326.0), (20437, 268.0)]
```

--------------------------------

### Configuring Query Parameters

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Example of configuring query parameters like timeoutMs at the engine level using connect_args.

```python
engine = create_engine(
        "pinot://localhost:8000/query/sql?controller=http://localhost:9000/",
        connect_args={"query_options": "use_multistage_engine=true;timeoutMs=10000"})

```

--------------------------------

### Connection String Format

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

The general format for the SQLAlchemy connection string to Apache Pinot.

```text
pinot+<protocol>://<broker-host>:<broker-port><broker-path>?controller=<controller-url>/
```

--------------------------------

### Authentication Connection String

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Connection string format including user credentials for authentication.

```text
pinot+https://<user>:<password>@<broker-host>:<broker-port><broker-path>?controller=https://<controller-host>:<controller-port>/[&&verify_ssl=<true/false>]
```

--------------------------------

### Basic Connection

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/db-api.md

Establishes a basic HTTP connection to the Pinot Broker and executes a SQL query.

```python
from pinotdb import connect

conn = connect(host='localhost', port=8000, path='/query/sql', scheme='http')
curs = conn.cursor()
curs.execute("""
    SELECT place,
           CAST(REGEXP_EXTRACT(place, '(.*),', 1) AS FLOAT) AS lat,
           CAST(REGEXP_EXTRACT(place, ',(.*)', 1) AS FLOAT) AS lon
      FROM places
     LIMIT 10
""")
for row in curs:
    print(row)
```

--------------------------------

### Database Context Connection

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/db-api.md

Connects to Pinot with a specified database context.

```python
from pinotdb import connect

conn = connect(
    host='localhost',
    port=8000,
    path='/query/sql',
    scheme='http',
    database='dbName'
)
curs = conn.cursor()
curs.execute("SELECT col1 FROM table1 LIMIT 10")
for row in curs:
    print(row)
```

--------------------------------

### Superset Multi-Stage Engine Configuration

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Configuration for enabling the multi-stage engine in Apache Superset.

```json
{"connect_args": {"use_multistage_engine": "true"}}
```

--------------------------------

### Asyncio Support with SQLAlchemy

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Example using create_async_engine for asyncio support with the async dialect, including explicit async HTTPS.

```python
from sqlalchemy import text
from sqlalchemy.ext.asyncio import create_async_engine

engine = create_async_engine(
    "pinot+async://localhost:8000/query/sql?controller=http://localhost:9000/"
)
# or, using explicit async HTTPS:
# engine = create_async_engine(
#     "pinot+https_async://localhost:443/query/sql?controller=https://localhost:9000/"
# )

async with engine.connect() as connection:
    result = await connection.execute(text("SELECT * FROM baseballStats LIMIT 5"))
    print(result.fetchall())
```

--------------------------------

### Database Context Connection String

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Connection string format including the database context.

```text
pinot+http://pinot-broker:8099/query/sql?controller=http://pinot-controller:9000/&database=dbName
```

--------------------------------

### Group By and Sum SQL to Pinot

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Example of sending a SQL query with GROUP BY and SUM to Pinot.

```python
Sending SQL to Pinot: SELECT AirlineID, sum(Cancelled) FROM airlineStats WHERE Year > 2010 GROUP BY AirlineID LIMIT 5
[20409, 40.0]
[19930, 16.0]
[19805, 60.0]
[19790, 115.0]
[20366, 172.0]
```

--------------------------------

### Sending SQL with String Literals to Pinot

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Example of sending a SQL query with string literals to Pinot.

```python
Sending SQL: "SELECT OriginCityName, sum(Cancelled) AS sum_cancelled FROM "airlineStats" WHERE Year>2010 GROUP BY OriginCityName ORDER BY sum_cancelled DESC LIMIT 5" to Pinot
[('Chicago, IL', 178.0), ('Atlanta, GA', 111.0), ('New York, NY', 65.0), ('Houston, TX', 62.0), ('Denver, CO', 49.0)]
```

--------------------------------

### Count(*) SQL to Pinot

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Example of sending a COUNT(*) SQL query to Pinot and receiving a result.

```python
Sending SQL to Pinot: SELECT count(*) FROM airlineStats LIMIT 5
[17772]
```

--------------------------------

### SQLAlchemy 2.x Query Example

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Sample script to query Pinot using SQLAlchemy 2.x with HTTP, explicit HTTP, explicit HTTPS, and multistage engine enabled.

```python
from sqlalchemy import *
from sqlalchemy.engine import create_engine
from sqlalchemy.schema import *

engine = create_engine('pinot://localhost:8099/query/sql?controller=http://localhost:9000/')  # uses HTTP by default :(
# or, using explicit HTTP:
# engine = create_engine('pinot+http://localhost:8099/query/sql?controller=http://localhost:9000/')
# or, using explicit HTTPS:
# engine = create_engine('pinot+https://localhost:8099/query/sql?controller=https://localhost:9000/')
# or, provide extra argument to connect with multi-stage engine enabled:
# engine = create_engine(
#     "pinot://localhost:8000/query/sql?controller=http://localhost:9000/",
#     connect_args={"use_multistage_engine": "true"}
# )

metadata = MetaData()
places = Table('places', metadata, autoload_with=engine)
query = select(func.count()).select_from(places)
with engine.connect() as connection:
    print(connection.execute(query).scalar())
```

--------------------------------

### Sending Count(*) SQL to Pinot (Alternative)

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Another example of sending a COUNT(*) SQL query to Pinot.

```python
Sending Count(*) SQL to Pinot
17773
```

--------------------------------

### Query Statistics

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/db-api.md

Retrieves and prints query statistics after executing a query.

```python
curs.execute("SELECT * FROM airlineStats LIMIT 10")
print(curs.query_stats.get("numServersQueried"))
print(curs.query_stats.get("numDocsScanned"))
print(curs.timeUsedMs)  # Backward compatible shorthand
```

--------------------------------

### HTTPS Connection String

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/sqlalchemy.md

Connection string format for using HTTPS with the SQLAlchemy dialect.

```text
pinot+https://<broker-host>:<broker-port><broker-path>?controller=https://<controller-host>:<controller-port>/
```

--------------------------------

### HTTPS Connection

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/db-api.md

Establishes an HTTPS connection to the Pinot Broker and executes a SQL query.

```python
from pinotdb import connect

conn = connect(host='localhost', port=443, path='/query/sql', scheme='https')
curs = conn.cursor()
curs.execute("SELECT * FROM places LIMIT 10")
for row in curs:
    print(row)
```

--------------------------------

### Max Flights by Origin City SQL to Pinot

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Example of sending a SQL query to find the maximum flights by origin city.

```python
Sending SQL to Pinot: select OriginCityName, max(Flights) from airlineStats group by OriginCityName ORDER BY max(Flights) DESC LIMIT 5
['Casper, WY', 1.0]
['Deadhorse, AK', 1.0]
['Austin, TX', 1.0]
['Chicago, IL', 1.0]
['Monterey, CA', 1.0]
```

--------------------------------

### Sum Cancelled by Origin City SQL to Pinot

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Example of sending a SQL query to find the sum of cancelled flights by origin city.

```python
Sending SQL to Pinot: SELECT OriginCityName, sum(Cancelled) AS sum_cancelled FROM airlineStats WHERE Year>2010 GROUP BY OriginCityName ORDER BY sum_cancelled DESC LIMIT 5
['Chicago, IL', 178.0]
['Atlanta, GA', 111.0]
['New York, NY', 65.0]
['Houston, TX', 62.0]
['Denver, CO', 49.0]
```

--------------------------------

### Manual release steps using Poetry and Git

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

A sequence of commands to manually build, publish, and tag a release using Poetry and Git.

```bash
$ BRANCH=master
$ VERSION=<new_version>
$ poetry version "$VERSION"
$ PINOTDB_VERSION=$(poetry version -s)
$ poetry build
$ poetry publish
$ git add pyproject.toml
$ git commit -m "Update version to pinotdb ${PINOTDB_VERSION}"
$ git tag "release-${PINOTDB_VERSION}"
$ git push origin "HEAD:${BRANCH}"
$ git push origin "release-${PINOTDB_VERSION}"
$ gh release create "release-${PINOTDB_VERSION}" \
    --title "Release release-${PINOTDB_VERSION}" \
    --generate-notes
```

--------------------------------

### Build and publish

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/AGENTS.md

Builds the package and publishes it to PyPI using Poetry.

```bash
poetry build
poetry publish
```

--------------------------------

### All Tests

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/contributing.md

Command to run all tests.

```bash
make test
```

--------------------------------

### Configure PyPI token with Poetry

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Configures Poetry to use a PyPI API token for publishing.

```shell
$ poetry config pypi-token.pypi <your_api_token_generated_from_pypi.org>
```

--------------------------------

### Development commands

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Commands to run for developing and testing the library, including integration tests, unit tests, and coverage reports.

```bash
make run-pinot
```

```bash
make init
```

```bash
make test
```

```bash
make coverage
```

--------------------------------

### Unit Tests

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/contributing.md

Command to run unit tests.

```bash
make test-unit
```

--------------------------------

### Publish with username and password using Poetry

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Publishes a package using Poetry with explicit username and password.

```shell
$ poetry publish --username=<your_username> --password='<your_password>'
```

--------------------------------

### Configure PyPI token (one-time)

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/AGENTS.md

Configures the PyPI token for publishing using Poetry.

```bash
poetry config pypi-token.pypi <token>
```

--------------------------------

### Linting

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/contributing.md

Command to run linting.

```bash
make lint
```

--------------------------------

### Cursor.execute() method

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/api-reference.md

Executes a SQL query against the Pinot Broker.

```python
curs.execute("SELECT * FROM myTable LIMIT 10")
curs.execute(
    "SELECT * FROM myTable LIMIT 10",
    queryOptions="useMultistageEngine=true"
)
```

--------------------------------

### connect() function

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/api-reference.md

Creates a synchronous DB-API connection to a Pinot Broker.

```python
from pinotdb import connect

conn = connect(
    host='localhost',
    port=8000,
    path='/query/sql',
    scheme='http',
    extra_request_headers=None,
    database='default',
    username=None,
    password=None,
    verify_ssl=True
)
```

--------------------------------

### connect_async() function

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/api-reference.md

Creates an asynchronous DB-API connection to a Pinot Broker.

```python
from pinotdb import connect_async

conn = await connect_async(
    host='localhost',
    port=8000,
    path='/query/sql',
    scheme='http',
    extra_request_headers=None,
    database='default',
    username=None,
    password=None,
    verify_ssl=True
)
```

--------------------------------

### Pinot with basic auth

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Connects to a Pinot broker using basic authentication over HTTPS.

```python
conn = connect(host="localhost", port=443, path="/query/sql", scheme="https", username="my-user", password="my-password", verify_ssl=True)
```

--------------------------------

### Passing additional query parameters

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Executes a query with additional options passed to the broker.

```python
curs.execute("select * from airlineStats air limit 10", queryOptions="useMultistageEngine=true")
```

--------------------------------

### Pass the Pinot database context

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Connects to a Pinot broker and specifies a database context for queries.

```python
from pinotdb import connect

# this assumes that 443 is the broker secure https port
conn = connect(host='localhost', port=8000, path='/query/sql', scheme='http', database='dbName')
curs = conn.cursor()
curs.execute("""
    SELECT col1 from table1 LIMIT 10
""")
for row in curs:
    print(row)
```

--------------------------------

### SQLAlchemy Connection String Format

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/api-reference.md

Format for SQLAlchemy connection strings.

```sql
pinot+<protocol>://<host>:<port><path>?controller=<controller-url>/
```

--------------------------------

### Run test suite under tox (multi-Python)

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/AGENTS.md

Executes the test suite using tox, which handles multi-Python environments.

```bash
tox
```

--------------------------------

### Bump version

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/AGENTS.md

Bumps the package version using Poetry.

```bash
poetry version patch
```

--------------------------------

### Connection.cursor() method

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/api-reference.md

Creates a new cursor for executing queries.

```python
curs = conn.cursor()
```

--------------------------------

### Coverage

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/docs/contributing.md

Command to generate test coverage.

```bash
make coverage
```

--------------------------------

### Using the DB API to query Pinot Broker directly (HTTP)

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Connects to a Pinot broker via HTTP and executes a SQL query.

```python
from pinotdb import connect

# this assumes 8000 is the broker port
conn = connect(host='localhost', port=8000, path='/query/sql', scheme='http')
curs = conn.cursor()
curs.execute("""
    SELECT place,
           CAST(REGEXP_EXTRACT(place, '(.*),', 1) AS FLOAT) AS lat,
           CAST(REGEXP_EXTRACT(place, ',(.*)', 1) AS FLOAT) AS lon
      FROM places
     LIMIT 10
""")
for row in curs:
    print(row)
```

--------------------------------

### Accessing broker query stats

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Retrieves and prints query statistics after executing a query.

```python
curs.execute("select * from airlineStats air limit 10")
print(curs.query_stats.get("numServersQueried"))
print(curs.query_stats.get("numDocsScanned"))
print(curs.timeUsedMs)  # Backward compatible shorthand
```

--------------------------------

### Using the DB API to query Pinot Broker directly (HTTPS)

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/README.md

Connects to a Pinot broker via HTTPS and executes a SQL query.

```python
from pinotdb import connect

# this assumes that 443 is the broker secure https port
conn = connect(host='localhost', port=443, path='/query/sql', scheme='https')
curs = conn.cursor()
curs.execute("""
    SELECT place,
           CAST(REGEXP_EXTRACT(place, '(.*),', 1) AS FLOAT) AS lat,
           CAST(REGEXP_EXTRACT(place, ',(.*)', 1) AS FLOAT) AS lon
      FROM places
     LIMIT 10
""")
for row in curs:
    print(row)
```

--------------------------------

### Run integration tests only

Source: https://github.com/python-pinot-dbapi/pinot-dbapi/blob/master/AGENTS.md

Runs only integration tests using Make.

```bash
make test-integration
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.