Documentation
¶
Overview ¶
Package drill is a database/sql driver for Apache Drill, which runs SQL over its REST interface. It registers the one name "drill", and takes a DSN of the form drill://user:pass@host:8047?key=value (D165).
db, err := sql.Open("drill", "drill://admin:pass@localhost:8047")
The driver reads. The server runs CREATE TABLE AS and refuses INSERT, UPDATE and DELETE, and the driver returns that refusal (D163). The server binds no argument, so the driver writes each argument as a literal (D165). The driver reads the answer one row at a time, and reads queryState at its end. A query that fails after some rows ends with FAILED and no message, and the driver reads the message from the profile of the query (D165). The server runs a query on when its client leaves, so the driver cancels it by its queryId when the context of the query ends (D165). Drill has no transactions. docs/DRILL.md holds what the driver knows about the server.
A column whose type changes between two files gives NULL for each value of the second type, with no sign in the answer. The driver cannot see this. Write typeof(column) in the statement to find such a value (D165).
Index ¶
Constants ¶
const ErrCanceled dbimp.Error = "the query was cancelled"
ErrCanceled is the error of a query that the server ended with queryState CANCELED, when the context of the query did not end. Someone else cancelled it, such as an administrator (measured).
const ErrCut dbimp.Error = "the answer was cut short"
ErrCut is the error of an answer that ends with no queryState. The server writes queryState last, so an answer without it did not end (D165).
const ErrLogin dbimp.Error = "the server asked for a login"
ErrLogin is the error of a request that the server sends to its login page, which is the answer to a wrong user or a wrong password (measured).
const Name = "drill"
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 Drillbit.
Host string
// Port is the port of the web server, 8047 by default.
Port int
// TLS is true to speak HTTPS.
TLS bool
// User and Password are the credentials, which the driver sends with
// basic authentication.
User string
Password string
// Schema is the schema of a table whose name has none, such as dfs.tmp,
// which the driver sends as defaultSchema. It is empty by default, and
// the driver then sends none.
Schema string
// AutoLimit is the most rows that the server sends for one query, which
// the driver sends as autoLimit. Zero sends none, and the server then
// sends every row. A result as long as AutoLimit does not say whether
// rows were left out (D165).
AutoLimit int
}
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 server. 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 Drill.
type Error ¶
type Error struct {
// HTTPStatus is the status code of the response.
HTTPStatus int
// QueryID is the queryId of the query, or empty when the answer has none.
QueryID string
// Kind is the start of the message of Drill, such as VALIDATION ERROR,
// PERMISSION ERROR or PLAN ERROR, and empty when the message has none.
Kind string
// Exception is the name of the Java class of the error, such as
// org.apache.calcite.runtime.CalciteContextException, and empty when the
// answer has none.
Exception string
// Message is the message of the server, or the text of the status when
// the answer has none.
Message string
// contains filtered or unexported fields
}
Error is an error that Drill reported. Drill answers most errors of a statement with HTTP 200 and queryState FAILED, such as a syntax error, an unknown table and a permission error. With the verbose option, which the driver sends, the answer holds the message. A request that the server cannot start gets HTTP 500 and "Query submission failed" with no reason, a body that is not JSON gets HTTP 400 in plain text, and a wrong password gets HTTP 307 to the login page with an empty body (measured).
func (*Error) Is ¶
Is reports whether err is target. It is ErrLogin for HTTP 307. It matches dbimp.ErrAuthentication only when the redirect goes to the login page, which is the answer to a wrong user or password. A PERMISSION ERROR, which comes with HTTP 200, is a missing permission and never matches (D197).
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 WithAutoLimit ¶
WithAutoLimit sets the most rows that the server sends for one statement, as the key autolimit of the DSN does, and sends it as autoLimit (D165). Zero sends none. A result as long as the limit does not say whether rows were left out.
func WithDatabase ¶
WithDatabase names the schema of one statement, as the key schema of the DSN does, such as "dfs.tmp". It is the schema of a table whose name has none, and the driver sends it as defaultSchema (D165).
func WithParameter ¶
WithParameter sets any key of the body of POST /query.json by its name, such as "options". The value is encoded with json/v2. A key named here replaces one that the driver sets itself, as in Couchbase. So "options" replaces the options that the driver sends, the verbose option of the errors too, and an error before any row then has no message (D165).
func WithReadonly ¶
WithReadonly asks the server to refuse a write. The server runs CREATE TABLE AS and has no setting that refuses it, so WithReadonly(true) fails the statement with dbimp.ErrNotSupported, and WithReadonly(false) asks for nothing (D163 and D165).
func WithSchema ¶
WithSchema sets the schema of one statement, as the key schema of the DSN does (D165).
func WithTimeout ¶
WithTimeout asks the server to stop the statement after d. The REST interface of Drill has no such setting, so a statement with a d above zero fails with dbimp.ErrNotSupported, and a d of zero asks for nothing. The context of the statement sets a limit that the driver keeps itself, and then cancels the query on the server (D165).
Source Files