Documentation
¶
Overview ¶
Package pinot is a database/sql driver for Apache Pinot, which runs SQL on a Broker over HTTP. It registers the one name "pinot", and takes a DSN of the form pinot://user:pass@host:8099?key=value (D129).
db, err := sql.Open("pinot", "pinot://admin:pass@localhost:8099")
The driver runs queries and takes no write, because the Broker refuses every write of rows (D128). Each query runs on the multi-stage engine, unless the key engine=single or WithEngine chooses the single-stage engine, which cuts a result that has no LIMIT at 10 rows (D131). The server binds no argument, so the driver writes each ? as a literal of Pinot (D132). Every query sends enableNullHandling=true, so a NULL reaches the caller as nil (D130). The driver reads the answer one token at a time, and when the context ends before the answer arrives, it cancels the query by the id that it gave the query (D133). docs/PINOT.md holds what the driver knows about the server.
Index ¶
Constants ¶
const ( // CancelKill sends DELETE /query/<id>?client=true for the id that the // driver gave the query. It is the default. CancelKill = "kill" // CancelNone sends nothing, and the query runs on to its end or its // timeout. CancelNone = "none" )
The values of the key cancel, which say how the driver stops a query on the server when its context ends (D133).
const ( // EngineMulti runs each query on the multi-stage engine, which returns // every row of a query that has no LIMIT. It is the default. EngineMulti = "multi" // EngineSingle runs each query on the single-stage engine, which returns // 10 rows of a query that has no LIMIT, and says nothing of the rows // that it left out. EngineSingle = "single" )
The values of the key engine, which say which engine of the Broker runs a query (D131).
const ( // AuthBasic sends the user and the password with basic authentication. // It is the default. AuthBasic = dbimp.AuthBasic // AuthBearer sends the password as a Bearer token. AuthBearer = dbimp.AuthBearer )
The values of the key auth, which say how the driver sends the password (D94).
const ErrPartial dbimp.Error = "the server marked the result as partial"
ErrPartial is the error of an answer that the server marked partialResult without an exception, as a join does when it stops at maxRowsInJoin with joinOverflowMode=BREAK (measured). After a row, it comes wrapped with dbimp.ErrIncomplete (D133).
const Name = "pinot"
Name is the name that the driver registers with database/sql, and the scheme of its DSN.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Config ¶
type Config struct {
// Host is the host of the Broker.
Host string
// Port is the port of the Broker, 8099 by default.
Port int
// TLS is true to speak HTTPS.
TLS bool
// User and Password are the credentials. The password can be a token
// (D94).
User string
Password string
// Auth is AuthBasic or AuthBearer (D94).
Auth string
// Cancel is CancelKill or CancelNone (D133).
Cancel string
// Engine is EngineMulti or EngineSingle (D131).
Engine string
}
Config is the configuration of a connector, which the DSN holds. The caller owns it (D7).
type Connector ¶
type Connector struct {
// contains filtered or unexported fields
}
Connector opens connections to one Broker. It owns its transport, and every connection shares it. A caller can build one from a Config and open it with sql.OpenDB.
func NewConnector ¶
NewConnector returns a Connector for cfg. The connector keeps a copy of cfg, and fills each field that is zero with its default.
type Driver ¶
type Driver struct{}
Driver is the database/sql driver for Apache Pinot.
type Error ¶
type Error struct {
// HTTPStatus is the status code of the response.
HTTPStatus int
// Code is the code of the first exception, or the HTTP status when the
// response held none.
Code int
// Message is the message of the first exception, or of the response.
Message string
// Exceptions holds every exception of the answer, the first one too.
Exceptions []Exception
// contains filtered or unexported fields
}
Error is an error that Pinot reported. A query that fails has HTTP 200, and its exceptions in the body (measured). Code and Message are those of the first exception, or those of the HTTP status for a response that holds none, such as HTTP 401 for a wrong password.
type Exception ¶
type Exception struct {
// Code is the code of the error, such as 150.
Code int `json:"errorCode"`
// Message is the message of the server.
Message string `json:"message"`
}
Exception is one exception of an answer of the Broker, such as 150 for a statement that does not parse, or 190 for a table that does not exist (measured).
type Option ¶
Option sets an option of one statement (D109). An option comes from the DSN, then from the context through WithOptions, then from an argument of the statement, and a later one wins.
func WithCancel ¶
WithCancel sets how the driver stops the query on the server when its context ends, CancelKill or CancelNone, as the key cancel of the DSN does (D133).
func WithDatabase ¶
WithDatabase would choose a database. Pinot has tables and no databases (D129), so a statement with it fails with dbimp.ErrNotSupported.
func WithEngine ¶
WithEngine sets the engine that runs the query, EngineMulti or EngineSingle, as the key engine of the DSN does (D131).
func WithParameter ¶
WithParameter sets any key of the body of POST /query/sql by its name, such as "trace". The value is encoded with json/v2. A key named here replaces one that the driver sets itself, as in Couchbase. So "queryOptions" replaces every query option that the driver sends, enableNullHandling and the id of the query too.
func WithReadonly ¶
WithReadonly asks that the statement write nothing. The Broker takes no write of any kind (D128), so every statement is read-only, and the option changes nothing.
func WithTimeout ¶
WithTimeout sets the time that the server gives the query, as the query option timeoutMs, which counts whole milliseconds, so the driver rounds d up to the next millisecond. The server stops a query that runs longer with the code 250 (measured). Zero leaves the timeout of the server, which is 10 seconds by default.
Source Files