Documentation
¶
Overview ¶
Package elasticsearch is a database/sql driver for Elasticsearch, which runs SQL through POST /_sql over HTTP. It registers the one name "elasticsearch", and takes a DSN of the form elasticsearch://user:pass@host:9200?key=value (D167).
db, err := sql.Open("elasticsearch", "elasticsearch://elastic:pass@localhost:9200")
The driver reads only. SQL in Elasticsearch takes SELECT, SHOW, DESCRIBE and SYS, and the server refuses every write with a parse error, which the driver returns (D163). A write goes through the document API of the server, which the driver does not speak. The server binds each argument from the array params. The driver reads each page one token at a time, follows the cursor to the last page, and closes the cursor of a result that the caller leaves before the end (D167). A failure on a later page wraps dbimp.ErrIncomplete (D107). The server cancels the statement when the client leaves, so a cancelled context only closes the request (measured). Elasticsearch has no transactions. docs/ELASTICSEARCH.md holds what the driver knows about the server.
Index ¶
- Constants
- func WithOptions(ctx context.Context, opts ...Option) context.Context
- type Config
- type Connector
- type Driver
- type Error
- type Option
- func WithCatalog(name string) Option
- func WithDatabase(name string) Option
- func WithFetchSize(n int) Option
- func WithFieldMultiValueLeniency(on bool) Option
- func WithParameter(name string, value any) Option
- func WithReadonly(bool) Option
- func WithTimeZone(name string) Option
- func WithTimeout(d time.Duration) Option
Constants ¶
const ( AuthBasic = dbimp.AuthBasic AuthAPIKey = "apikey" )
The values of the key auth. AuthBasic sends the user and the password with basic authentication. AuthAPIKey sends the password as an API key, in the header Authorization with the scheme ApiKey, and no user (D94 and D167).
const Name = "elasticsearch"
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 server.
Host string
// Port is the port of the HTTP interface, 9200 by default.
Port int
// TLS is true to speak HTTPS.
TLS bool
// Auth is AuthBasic or AuthAPIKey, and AuthBasic by default.
Auth string
// User and Password are the credentials. With AuthBasic the driver sends
// both with basic authentication. With AuthAPIKey it sends the password
// as an API key. With neither, the driver sends no credentials.
User string
Password string
// FetchSize is the rows of a page, as fetch_size, 1000 by default. The
// server cannot give a page larger than index.max_result_window of an
// index, which is 10000 by default (measured).
FetchSize int
// TimeZone is the time zone of each statement, as time_zone, such as UTC,
// Asia/Jakarta or +05:30. It is UTC by default.
TimeZone string
// FieldMultiValueLeniency sets field_multi_value_leniency. It is false by
// default, and then a field that holds several values fails the
// statement. When it is true, such a field gives its first value, and
// the other values are lost with no sign (D167).
FieldMultiValueLeniency bool
// Catalog is the cluster of each statement, as catalog, and empty for the
// local cluster.
Catalog 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 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 Elasticsearch.
type Error ¶
type Error struct {
// HTTPStatus is the status code of the response.
HTTPStatus int
// Type is the type of the error, such as parsing_exception or
// verification_exception, and empty when the answer has none.
Type string
// Reason is the reason of the error, or the text of the answer when it
// has no JSON object.
Reason string
// RootType and RootReason are the type and the reason of the first root
// cause, and empty when the answer has none. The root cause names the
// fault itself where the error wraps another, such as
// search_timeout_exception inside search_phase_execution_exception.
RootType string
RootReason string
// contains filtered or unexported fields
}
Error is an error that Elasticsearch reported. Elasticsearch answers an error with a status that is not 2xx and a JSON object, such as HTTP 400 with parsing_exception for a syntax error, HTTP 500 with arithmetic_exception for a division by zero, and HTTP 404 with search_context_missing_exception for a cursor that is gone. A statement that passed its request_timeout gives HTTP 504 on 8.19.22 and HTTP 429 on 9.4.6 and 9.5.3, so HTTP 429 does not always mean a limit on the rate. A wrong password is HTTP 401, and a missing privilege is HTTP 403 with security_exception (measured). No error arrived with HTTP 200 (measured).
func (*Error) Is ¶ added in v0.18.0
Is reports whether err matches target. It matches dbimp.ErrAuthentication when the status is HTTP 401, which is a wrong password with security_exception (recorded: "a wrong password"). Every other refusal does not match, such as HTTP 403 for a missing permission (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 WithCatalog ¶
WithCatalog sets the cluster of the statement, as catalog, as the key catalog of the DSN does. The name of the local cluster works, and the name of a cluster that is not configured fails with HTTP 404 (measured).
func WithDatabase ¶
WithDatabase names the database of one statement. Elasticsearch has no database to choose, and its catalog is a cluster, which WithCatalog sets (D167). A statement with WithDatabase fails with dbimp.ErrNotSupported.
func WithFetchSize ¶
WithFetchSize sets the rows of a page, as fetch_size, as the key fetch_size of the DSN does.
func WithFieldMultiValueLeniency ¶
WithFieldMultiValueLeniency sets field_multi_value_leniency, as the key of the DSN does. When it is true, a field that holds several values gives its first value, and the other values are lost with no sign (D167).
func WithParameter ¶
WithParameter sets any key of the body of POST /_sql by its name, such as "filter" or "runtime_mappings". The value is encoded with json/v2. A key named here replaces one that the driver sets itself, as in Couchbase, so "params" replaces the arguments of the statement. The key applies to the first request of a statement and not to the request for each next page, which sends only the cursor and the keys of the driver.
func WithReadonly ¶
WithReadonly asks that the statement write nothing. SQL in Elasticsearch takes no write of any kind (D163), so every statement is read-only, and the option changes nothing.
func WithTimeZone ¶
WithTimeZone sets the time zone of the statement, as time_zone, as the key time_zone of the DSN does.
func WithTimeout ¶
WithTimeout sets the time that the server gives the statement, as request_timeout. The server counts milliseconds, so the driver rounds d up to the next millisecond. The server stops a statement that runs longer with search_timeout_exception, and HTTP 504 on 8.19.22 and HTTP 429 on 9.4.6 and 9.5.3 (measured). Zero sends no timeout, and the server uses its own.
Source Files