README
¶
Generated Documentation and Embedded Help Texts
Many parts of the parser package include special consideration for generation
or other production of user-facing documentation. This includes interactive help
messages, generated documentation of the set of available functions, or diagrams
of the various expressions.
Generated documentation is produced and maintained at compile time, while the interactive, contextual help is returned at runtime.
We equip the generated parser with the ability to report contextual help in two circumstances:
- when the user explicitly requests help with the HELPTOKEN (current syntax: standalone "
??") - when the user makes a grammatical mistake (e.g.
INSERT sometable INTO(x, y) ...)
We use the docgen tool to produce the generated documentation files that are
then included in the broader (handwritten) published documentation.
Help texts embedded in the grammar
The help is embedded in the grammar using special markers in yacc comments, for example:
// %Help: HELPKEY - shortdescription
// %Category: SomeCat
// %Text: whatever until next %marker at start of line, or non-comment.
// %SeeAlso: whatever until next %marker at start of line, or non-comment.
// %End (optional)
The "HELPKEY" becomes the map key in the generated Go map.
These texts are extracted automatically by help.awk and converted
into a Go data structure in help_messages.go.
Support in the parser
Primary mechanism - LALR error recovery
The primary mechanism is leveraging error recovery in LALR parsers
using the special error token [1] [2]: when an unexpected token is
encountered, the LALR parser will pop tokens on the stack until the
prefix matches a grammar rule with the special "error" token (if
any). If such a rule exists, its action is used to reduce and the
erroneous tokens are discarded.
This mechanism is used both when the user makes a mistake, and when the user inserts the HELPTOKEN in the middle of a statement. When present in the middle of a statement, HELPTOKEN is considered an error and triggers the error recovery.
We use this for contextual help by providing error rules that
generate a contextual help text during LALR error recovery.
For example:
backup_stmt:
BACKUP targets TO string_or_placeholder opt_as_of_clause opt_incremental opt_with_options
{
$$.val = &Backup{Targets: $2.targetList(), To: $4.expr(), IncrementalFrom: $6.exprs(), AsOf: $5.asOfClause(), Options: $7.kvOptions()}
}
| BACKUP error { return helpWith(sqllex, `BACKUP`) }
In this example, the grammar specifies that if the BACKUP keyword is
followed by some input tokens such that the first (valid) grammar rule
doesn't apply, the parser will "recover from the error" by
backtracking up until the point it only sees BACKUP on the stack
followed by non-parsable tokens, at which points it takes the error
rule and executes its action.
The action is return helpWith(...). What this does is:
- halts parsing (the generated parser executes all actions
in a big loop; a
returninterrupts this loop); - makes the parser return with an error (the
helpWithfunction returns non-zero); - extends the parsing error message with a help text; this help text can subsequently be exploited in a client to display the help message in a friendly manner.
Code generation
Since the pattern "{ return helpWith(sqllex, ...) }" is common, we also implement
a shorthand syntax based on comments, for example:
backup_stmt:
...
| BACKUP error // SHOW HELP: BACKUP
The special comment syntax "SHOW HELP: XXXX" is substituted by means
of an auxiliary script (replace_help_rules.awk) into the form
explained above.
Secondary mechanism - explicit help token
The mechanism described above works both when the user make a grammatical error and when they place the HELPTOKEN in the middle of a statement, rendering it invalid.
However for contextual help this is not sufficient: what happens if the user requests HELPTOKEN at a position in the grammar where everything before is a complete, valid SQL input?
For example: DELETE FROM foo ?
When encountering this input, the LALR parser will see DELETE FROM foo first, then reduce using the DELETE action because everything
up to this point is a valid DELETE statement. When the HELPTOKEN is
encountered, the statement has already been completed and the LALR
parser doesn't 'know' any more that it was in the context of a DELETE
statement.
If we try to place an error-based recovery rule at the top-level:
stmt:
alter_stmt
| backup_stmt
| ...
| delete_stmt
| ...
| error { ??? }
This wouldn't work: the code inside the error action cannot
"observe" the tokens observed so far and there would be no way to know
whether the error should be about DELETE, or instead about ALTER,
BACKUP, etc.
So in order to handle HELPTOKEN after a valid statement, we must place it in a rule where the context is still available, that is before the statement's grammar rule is reduced.
Where would that be? Suppose we had a simple statement rule:
somesimplestmt:
SIMPLE DO SOMETHING { $$ = reduce(...) }
| SIMPLE error { help ... }
We could extend with:
somesimplestmt:
SIMPLE DO SOMETHING { $$ = reduce(...) }
| SIMPLE DO SOMETHING HELPTOKEN { help ... }
| SIMPLE error { help ... }
(the alternative also works:
somesimplestmt:
SIMPLE DO SOMETHING { $$ = reduce(...) }
| SIMPLE DO SOMETHING error { help ... }
| SIMPLE error { help ... }
)
That is all fine and dandy, but in SQL we have statements with many alternate forms, for example:
alter_rename_table_stmt:
ALTER TABLE relation_expr RENAME TO qualified_name { ... }
| ALTER TABLE IF EXISTS relation_expr RENAME TO qualified_name { ... }
| ALTER TABLE relation_expr RENAME opt_column name TO name { ... }
| ALTER TABLE IF EXISTS relation_expr RENAME opt_column name TO name { ... }
To add complementary handling of the help token at the end of valid statements we could, but would hate to, duplicate all the rules:
alter_rename_table_stmt:
ALTER TABLE relation_expr RENAME TO qualified_name { ... }
| ALTER TABLE relation_expr RENAME TO qualified_name HELPTOKEN { help ... }
| ALTER TABLE IF EXISTS relation_expr RENAME TO qualified_name { ... }
| ALTER TABLE IF EXISTS relation_expr RENAME TO qualified_name HELPTOKEN { help ... }
| ALTER TABLE relation_expr RENAME opt_column name TO name { ... }
| ALTER TABLE relation_expr RENAME opt_column name TO name HELPTOKEN { help ... }
| ALTER TABLE IF EXISTS relation_expr RENAME opt_column name TO name { ... }
| ALTER TABLE IF EXISTS relation_expr RENAME opt_column name TO name HELPTOKEN { help ... }
This duplication is horrendous (not to mention hard to maintain), so instead we should attempt to factor the help token in a context where it is still known that we are dealing just with that statement.
The following works:
alter_rename_table_stmt:
real_alter_rename_table_stmt { $$ = $1 }
| real_alter_rename_table_stmt HELPTOKEN { help ... }
real_alter_rename_table_stmt:
ALTER TABLE relation_expr RENAME TO qualified_name { ... }
| ALTER TABLE IF EXISTS relation_expr RENAME TO qualified_name { ... }
| ALTER TABLE relation_expr RENAME opt_column name TO name { ... }
| ALTER TABLE IF EXISTS relation_expr RENAME opt_column name TO name { ... }
Or does it? Without anything else, yacc complains with a "shift/reduce
conflict". The reason is coming from the ambiguity: when the parsing
stack contains everything sufficient to match a
real_alter_rename_table_stmt, there is a choice between reducing
the simple form alter_rename_table_stmt: real_alter_rename_table_stmt, or shifting into the more complex
form alter_rename_table_stmt: real_alter_rename_table_stmt HELPTOKEN.
This is another form of the textbook situation when yacc is used to
parse if-else statements in a programming language: the rule stmt: IF cond THEN body | IF cond THEN body ELSE body is ambiguous (and yields
a shift/reduce conflict) for exactly the same reason.
The solution here is also straight out of a textbook: one simply informs yacc of the relative priority between the two candidate rules. In this case, when faced with a neutral choice, we encourage yacc to shift. The particular mechanism is to tell yacc that one rule has a higher priority than another.
It just so happens however that the yacc language only allows us to set relative priorities of tokens, not rules. And here we have a problem, of the two rules that need to be prioritized, only one has a token to work with (the one with HELPTOKEN). Which token should we prioritize for the other?
Conveniently yacc knows about this trouble and offers us an awkward,
but working solution: we can tell it "use for this rule the same
priority level as an existing token, even though the token is not part
of the rule". The syntax for this is rule %prec TOKEN.
We can then use this as follows:
alter_rename_table_stmt:
real_alter_rename_table_stmt %prec LOWTOKEN { $$ = $1 }
| real_alter_rename_table_stmt HELPTOKEN %prec HIGHTOKEN { help ... }
We could create two new pseudo-tokens for this (called LOWTOKEN and
HIGHTOKEN) however conveniently we can also reuse otherwise valid
tokens that have known relative priorities. We settled in our case on
VALUES (low priority) and UMINUS (high priority).
Code generation
With the latter mechanism presented above the pattern
rule:
somerule %prec VALUES
| somerule HELPTOKEN %prec UMINUS { help ...}`
becomes super common, so we automate it with the following special syntax:
rule:
somerule // EXTEND WITH HELP: XXX
And the code replacement in replace_help_rules.awk expands this to
the form above automatically.
Generated Documentation
Documentation of the SQL functions and operators is generated by the docgen
utility, using make generate PKG=./docs/.... The markdown-formatted files are
kept in docs/generated/sql and should be re-generated whenever the
functions/operators they document change, and indeed if regenerating produces a
diff, a CI failure is expected.
References
Documentation
¶
Index ¶
- Constants
- Variables
- func GetTypeFromValidSQLSyntax(sql string) (tree.ResolvableTypeReference, error)
- func GetTypeReferenceFromName(typeName tree.Name) (tree.ResolvableTypeReference, error)
- func NakedIntTypeFromDefaultIntSize(defaultIntSize int32) *types.T
- func ParseExpr(sql string) (tree.Expr, error)
- func ParseExprWithInt(sql string, nakedIntType *types.T) (tree.Expr, error)
- func ParseExprs(sql []string) (tree.Exprs, error)
- func ParseQualifiedTableName(sql string) (*tree.TableName, error)
- func ParseTableName(sql string) (*tree.UnresolvedObjectName, error)
- func RunShowSyntax(ctx context.Context, stmt string, ...)
- func SplitFirstStatement(sql string) (pos int, ok bool)
- type HelpMessage
- type HelpMessageBody
- type Parser
- type Statement
- type Statements
- type TokenString
Constants ¶
const ABORT = lexbase.ABORT
const ABSOLUTE = lexbase.ABSOLUTE
const ACCESS = lexbase.ACCESS
const ACTION = lexbase.ACTION
const ADD = lexbase.ADD
const ADMIN = lexbase.ADMIN
const AFTER = lexbase.AFTER
const AGGREGATE = lexbase.AGGREGATE
const ALL = lexbase.ALL
const ALTER = lexbase.ALTER
const ALWAYS = lexbase.ALWAYS
const ANALYSE = lexbase.ANALYSE
const ANALYZE = lexbase.ANALYZE
const AND = lexbase.AND
const AND_AND = lexbase.AND_AND
const ANNOTATE_TYPE = lexbase.ANNOTATE_TYPE
const ANY = lexbase.ANY
const ARRAY = lexbase.ARRAY
const AS = lexbase.AS
const ASC = lexbase.ASC
const ASENSITIVE = lexbase.ASENSITIVE
const ASYMMETRIC = lexbase.ASYMMETRIC
const AS_LA = lexbase.AS_LA
const AT = lexbase.AT
const ATTRIBUTE = lexbase.ATTRIBUTE
const AUTHORIZATION = lexbase.AUTHORIZATION
const AUTOMATIC = lexbase.AUTOMATIC
const AVAILABILITY = lexbase.AVAILABILITY
const BACKUP = lexbase.BACKUP
const BACKUPS = lexbase.BACKUPS
const BACKWARD = lexbase.BACKWARD
const BCONST = lexbase.BCONST
const BEFORE = lexbase.BEFORE
const BEGIN = lexbase.BEGIN
const BETWEEN = lexbase.BETWEEN
const BIGINT = lexbase.BIGINT
const BIGSERIAL = lexbase.BIGSERIAL
const BINARY = lexbase.BINARY
const BIT = lexbase.BIT
const BITCONST = lexbase.BITCONST
const BOOLEAN = lexbase.BOOLEAN
const BOTH = lexbase.BOTH
const BOX2D = lexbase.BOX2D
const BUCKET_COUNT = lexbase.BUCKET_COUNT
const BUNDLE = lexbase.BUNDLE
const BY = lexbase.BY
const CACHE = lexbase.CACHE
const CANCEL = lexbase.CANCEL
const CANCELQUERY = lexbase.CANCELQUERY
const CASCADE = lexbase.CASCADE
const CASE = lexbase.CASE
const CAST = lexbase.CAST
const CBRT = lexbase.CBRT
const CHANGEFEED = lexbase.CHANGEFEED
const CHAR = lexbase.CHAR
const CHARACTER = lexbase.CHARACTER
const CHARACTERISTICS = lexbase.CHARACTERISTICS
const CHECK = lexbase.CHECK
const CLOSE = lexbase.CLOSE
const CLUSTER = lexbase.CLUSTER
const COALESCE = lexbase.COALESCE
const COLLATE = lexbase.COLLATE
const COLLATION = lexbase.COLLATION
const COLUMN = lexbase.COLUMN
const COLUMNS = lexbase.COLUMNS
const COMMENT = lexbase.COMMENT
const COMMENTS = lexbase.COMMENTS
const COMMIT = lexbase.COMMIT
const COMMITTED = lexbase.COMMITTED
const COMPACT = lexbase.COMPACT
const COMPLETE = lexbase.COMPLETE
const COMPLETIONS = lexbase.COMPLETIONS
const CONCAT = lexbase.CONCAT
const CONCURRENTLY = lexbase.CONCURRENTLY
const CONFIGURATION = lexbase.CONFIGURATION
const CONFIGURATIONS = lexbase.CONFIGURATIONS
const CONFIGURE = lexbase.CONFIGURE
const CONFLICT = lexbase.CONFLICT
const CONNECTION = lexbase.CONNECTION
const CONSTRAINT = lexbase.CONSTRAINT
const CONSTRAINTS = lexbase.CONSTRAINTS
const CONTAINED_BY = lexbase.CONTAINED_BY
const CONTAINS = lexbase.CONTAINS
const CONTROLCHANGEFEED = lexbase.CONTROLCHANGEFEED
const CONTROLJOB = lexbase.CONTROLJOB
const CONVERSION = lexbase.CONVERSION
const CONVERT = lexbase.CONVERT
const COPY = lexbase.COPY
const COVERING = lexbase.COVERING
const CREATE = lexbase.CREATE
const CREATEDB = lexbase.CREATEDB
const CREATELOGIN = lexbase.CREATELOGIN
const CREATEROLE = lexbase.CREATEROLE
const CROSS = lexbase.CROSS
const CSV = lexbase.CSV
const CUBE = lexbase.CUBE
const CURRENT = lexbase.CURRENT
const CURRENT_CATALOG = lexbase.CURRENT_CATALOG
const CURRENT_DATE = lexbase.CURRENT_DATE
const CURRENT_ROLE = lexbase.CURRENT_ROLE
const CURRENT_SCHEMA = lexbase.CURRENT_SCHEMA
const CURRENT_TIME = lexbase.CURRENT_TIME
const CURRENT_TIMESTAMP = lexbase.CURRENT_TIMESTAMP
const CURRENT_USER = lexbase.CURRENT_USER
const CURSOR = lexbase.CURSOR
const CYCLE = lexbase.CYCLE
const DATA = lexbase.DATA
const DATABASE = lexbase.DATABASE
const DATABASES = lexbase.DATABASES
const DATE = lexbase.DATE
const DAY = lexbase.DAY
const DEALLOCATE = lexbase.DEALLOCATE
const DEBUG_PAUSE_ON = lexbase.DEBUG_PAUSE_ON
const DEC = lexbase.DEC
const DECIMAL = lexbase.DECIMAL
const DECLARE = lexbase.DECLARE
const DEFAULT = lexbase.DEFAULT
const DEFAULTS = lexbase.DEFAULTS
const DEFERRABLE = lexbase.DEFERRABLE
const DEFERRED = lexbase.DEFERRED
const DELETE = lexbase.DELETE
const DELIMITER = lexbase.DELIMITER
const DESC = lexbase.DESC
const DESTINATION = lexbase.DESTINATION
const DETACHED = lexbase.DETACHED
const DISCARD = lexbase.DISCARD
const DISTINCT = lexbase.DISTINCT
const DO = lexbase.DO
const DOMAIN = lexbase.DOMAIN
const DOT_DOT = lexbase.DOT_DOT
const DOUBLE = lexbase.DOUBLE
const DROP = lexbase.DROP
const ELSE = lexbase.ELSE
const ENCODING = lexbase.ENCODING
const ENCRYPTED = lexbase.ENCRYPTED
const ENCRYPTION_PASSPHRASE = lexbase.ENCRYPTION_PASSPHRASE
const END = lexbase.END
const ENUM = lexbase.ENUM
const ENUMS = lexbase.ENUMS
const ERROR = lexbase.ERROR
const ESCAPE = lexbase.ESCAPE
const EXCEPT = lexbase.EXCEPT
const EXCLUDE = lexbase.EXCLUDE
const EXCLUDING = lexbase.EXCLUDING
const EXECUTE = lexbase.EXECUTE
const EXECUTION = lexbase.EXECUTION
const EXISTS = lexbase.EXISTS
const EXPERIMENTAL = lexbase.EXPERIMENTAL
const EXPERIMENTAL_AUDIT = lexbase.EXPERIMENTAL_AUDIT
const EXPERIMENTAL_FINGERPRINTS = lexbase.EXPERIMENTAL_FINGERPRINTS
const EXPERIMENTAL_RELOCATE = lexbase.EXPERIMENTAL_RELOCATE
const EXPERIMENTAL_REPLICA = lexbase.EXPERIMENTAL_REPLICA
const EXPIRATION = lexbase.EXPIRATION
const EXPLAIN = lexbase.EXPLAIN
const EXPORT = lexbase.EXPORT
const EXTENSION = lexbase.EXTENSION
const EXTRACT = lexbase.EXTRACT
const EXTRACT_DURATION = lexbase.EXTRACT_DURATION
const FAILURE = lexbase.FAILURE
const FALSE = lexbase.FALSE
const FAMILY = lexbase.FAMILY
const FCONST = lexbase.FCONST
const FETCH = lexbase.FETCH
const FETCHTEXT = lexbase.FETCHTEXT
const FETCHTEXT_PATH = lexbase.FETCHTEXT_PATH
const FETCHVAL = lexbase.FETCHVAL
const FETCHVAL_PATH = lexbase.FETCHVAL_PATH
const FILES = lexbase.FILES
const FILTER = lexbase.FILTER
const FIRST = lexbase.FIRST
const FLOAT = lexbase.FLOAT
const FLOAT4 = lexbase.FLOAT4
const FLOAT8 = lexbase.FLOAT8
const FLOORDIV = lexbase.FLOORDIV
const FOLLOWING = lexbase.FOLLOWING
const FOR = lexbase.FOR
const FORCE = lexbase.FORCE
const FORCE_INDEX = lexbase.FORCE_INDEX
const FORCE_ZIGZAG = lexbase.FORCE_ZIGZAG
const FOREIGN = lexbase.FOREIGN
const FORWARD = lexbase.FORWARD
const FROM = lexbase.FROM
const FULL = lexbase.FULL
const FUNCTION = lexbase.FUNCTION
const FUNCTIONS = lexbase.FUNCTIONS
const GENERATED = lexbase.GENERATED
const GENERATED_ALWAYS = lexbase.GENERATED_ALWAYS
const GENERATED_BY_DEFAULT = lexbase.GENERATED_BY_DEFAULT
const GEOGRAPHY = lexbase.GEOGRAPHY
const GEOMETRY = lexbase.GEOMETRY
const GEOMETRYCOLLECTION = lexbase.GEOMETRYCOLLECTION
const GEOMETRYCOLLECTIONM = lexbase.GEOMETRYCOLLECTIONM
const GEOMETRYCOLLECTIONZ = lexbase.GEOMETRYCOLLECTIONZ
const GEOMETRYCOLLECTIONZM = lexbase.GEOMETRYCOLLECTIONZM
const GEOMETRYM = lexbase.GEOMETRYM
const GEOMETRYZ = lexbase.GEOMETRYZ
const GEOMETRYZM = lexbase.GEOMETRYZM
const GLOBAL = lexbase.GLOBAL
const GOAL = lexbase.GOAL
const GRANT = lexbase.GRANT
const GRANTS = lexbase.GRANTS
const GREATER_EQUALS = lexbase.GREATER_EQUALS
const GREATEST = lexbase.GREATEST
const GROUP = lexbase.GROUP
const GROUPING = lexbase.GROUPING
const GROUPS = lexbase.GROUPS
const HASH = lexbase.HASH
const HAVING = lexbase.HAVING
const HELPTOKEN = lexbase.HELPTOKEN
const HIGH = lexbase.HIGH
const HISTOGRAM = lexbase.HISTOGRAM
const HOLD = lexbase.HOLD
const HOUR = lexbase.HOUR
const ICONST = lexbase.ICONST
const IDENT = lexbase.IDENT
const IDENTITY = lexbase.IDENTITY
const IF = lexbase.IF
const IFERROR = lexbase.IFERROR
const IFNULL = lexbase.IFNULL
const IGNORE_FOREIGN_KEYS = lexbase.IGNORE_FOREIGN_KEYS
const ILIKE = lexbase.ILIKE
const IMMEDIATE = lexbase.IMMEDIATE
const IMPORT = lexbase.IMPORT
const IN = lexbase.IN
const INCLUDE = lexbase.INCLUDE
const INCLUDING = lexbase.INCLUDING
const INCREMENT = lexbase.INCREMENT
const INCREMENTAL = lexbase.INCREMENTAL
const INCREMENTAL_LOCATION = lexbase.INCREMENTAL_LOCATION
const INDEX = lexbase.INDEX
const INDEXES = lexbase.INDEXES
const INET = lexbase.INET
const INET_CONTAINED_BY_OR_EQUALS = lexbase.INET_CONTAINED_BY_OR_EQUALS
const INET_CONTAINS_OR_EQUALS = lexbase.INET_CONTAINS_OR_EQUALS
const INHERITS = lexbase.INHERITS
const INITIALLY = lexbase.INITIALLY
const INJECT = lexbase.INJECT
const INNER = lexbase.INNER
const INSENSITIVE = lexbase.INSENSITIVE
const INSERT = lexbase.INSERT
const INT = lexbase.INT
const INTEGER = lexbase.INTEGER
const INTERSECT = lexbase.INTERSECT
const INTERVAL = lexbase.INTERVAL
const INTERVAL_SIMPLE = lexbase.INTERVAL_SIMPLE
const INTO = lexbase.INTO
const INTO_DB = lexbase.INTO_DB
const INVERTED = lexbase.INVERTED
const IS = lexbase.IS
const ISERROR = lexbase.ISERROR
const ISNULL = lexbase.ISNULL
const ISOLATION = lexbase.ISOLATION
const JOB = lexbase.JOB
const JOBS = lexbase.JOBS
const JOIN = lexbase.JOIN
const JSON = lexbase.JSON
const JSONB = lexbase.JSONB
const JSON_ALL_EXISTS = lexbase.JSON_ALL_EXISTS
const JSON_SOME_EXISTS = lexbase.JSON_SOME_EXISTS
const KEY = lexbase.KEY
const KEYS = lexbase.KEYS
const KMS = lexbase.KMS
const KV = lexbase.KV
const LANGUAGE = lexbase.LANGUAGE
const LAST = lexbase.LAST
const LATERAL = lexbase.LATERAL
const LATEST = lexbase.LATEST
const LC_COLLATE = lexbase.LC_COLLATE
const LC_CTYPE = lexbase.LC_CTYPE
const LEADING = lexbase.LEADING
const LEASE = lexbase.LEASE
const LEAST = lexbase.LEAST
const LEFT = lexbase.LEFT
const LESS = lexbase.LESS
const LESS_EQUALS = lexbase.LESS_EQUALS
const LEVEL = lexbase.LEVEL
const LIKE = lexbase.LIKE
const LIMIT = lexbase.LIMIT
const LINESTRING = lexbase.LINESTRING
const LINESTRINGM = lexbase.LINESTRINGM
const LINESTRINGZ = lexbase.LINESTRINGZ
const LINESTRINGZM = lexbase.LINESTRINGZM
const LIST = lexbase.LIST
const LOCAL = lexbase.LOCAL
const LOCALITY = lexbase.LOCALITY
const LOCALTIME = lexbase.LOCALTIME
const LOCALTIMESTAMP = lexbase.LOCALTIMESTAMP
const LOCKED = lexbase.LOCKED
const LOGIN = lexbase.LOGIN
const LOOKUP = lexbase.LOOKUP
const LOW = lexbase.LOW
const LSHIFT = lexbase.LSHIFT
const MATCH = lexbase.MATCH
const MATERIALIZED = lexbase.MATERIALIZED
const MAXVALUE = lexbase.MAXVALUE
const MERGE = lexbase.MERGE
const METHOD = lexbase.METHOD
const MINUTE = lexbase.MINUTE
const MINVALUE = lexbase.MINVALUE
const MODIFYCLUSTERSETTING = lexbase.MODIFYCLUSTERSETTING
const MONTH = lexbase.MONTH
const MOVE = lexbase.MOVE
const MULTILINESTRING = lexbase.MULTILINESTRING
const MULTILINESTRINGM = lexbase.MULTILINESTRINGM
const MULTILINESTRINGZ = lexbase.MULTILINESTRINGZ
const MULTILINESTRINGZM = lexbase.MULTILINESTRINGZM
const MULTIPOINT = lexbase.MULTIPOINT
const MULTIPOINTM = lexbase.MULTIPOINTM
const MULTIPOINTZ = lexbase.MULTIPOINTZ
const MULTIPOINTZM = lexbase.MULTIPOINTZM
const MULTIPOLYGON = lexbase.MULTIPOLYGON
const MULTIPOLYGONM = lexbase.MULTIPOLYGONM
const MULTIPOLYGONZ = lexbase.MULTIPOLYGONZ
const MULTIPOLYGONZM = lexbase.MULTIPOLYGONZM
const MaxInt = int(MaxUint >> 1)
const MaxUint = ^uint(0)
const NAME = lexbase.NAME
const NAMES = lexbase.NAMES
const NAN = lexbase.NAN
const NATURAL = lexbase.NATURAL
const NEVER = lexbase.NEVER
const NEW_DB_NAME = lexbase.NEW_DB_NAME
const NEW_KMS = lexbase.NEW_KMS
const NEXT = lexbase.NEXT
const NO = lexbase.NO
const NOCANCELQUERY = lexbase.NOCANCELQUERY
const NOCONTROLCHANGEFEED = lexbase.NOCONTROLCHANGEFEED
const NOCONTROLJOB = lexbase.NOCONTROLJOB
const NOCREATEDB = lexbase.NOCREATEDB
const NOCREATELOGIN = lexbase.NOCREATELOGIN
const NOCREATEROLE = lexbase.NOCREATEROLE
const NOLOGIN = lexbase.NOLOGIN
const NOMODIFYCLUSTERSETTING = lexbase.NOMODIFYCLUSTERSETTING
const NONE = lexbase.NONE
const NONVOTERS = lexbase.NONVOTERS
const NORMAL = lexbase.NORMAL
const NOSQLLOGIN = lexbase.NOSQLLOGIN
const NOT = lexbase.NOT
const NOTHING = lexbase.NOTHING
const NOTNULL = lexbase.NOTNULL
const NOT_EQUALS = lexbase.NOT_EQUALS
const NOT_LA = lexbase.NOT_LA
const NOT_REGIMATCH = lexbase.NOT_REGIMATCH
const NOT_REGMATCH = lexbase.NOT_REGMATCH
const NOVIEWACTIVITY = lexbase.NOVIEWACTIVITY
const NOVIEWACTIVITYREDACTED = lexbase.NOVIEWACTIVITYREDACTED
const NOVIEWCLUSTERSETTING = lexbase.NOVIEWCLUSTERSETTING
const NOWAIT = lexbase.NOWAIT
const NO_FULL_SCAN = lexbase.NO_FULL_SCAN
const NO_INDEX_JOIN = lexbase.NO_INDEX_JOIN
const NO_ZIGZAG_JOIN = lexbase.NO_ZIGZAG_JOIN
const NULL = lexbase.NULL
const NULLIF = lexbase.NULLIF
const NULLS = lexbase.NULLS
const NULLS_LA = lexbase.NULLS_LA
const NUMERIC = lexbase.NUMERIC
const OF = lexbase.OF
const OFF = lexbase.OFF
const OFFSET = lexbase.OFFSET
const OID = lexbase.OID
const OIDS = lexbase.OIDS
const OIDVECTOR = lexbase.OIDVECTOR
const OLD_KMS = lexbase.OLD_KMS
const ON = lexbase.ON
const ONLY = lexbase.ONLY
const ON_LA = lexbase.ON_LA
const OPERATOR = lexbase.OPERATOR
const OPT = lexbase.OPT
const OPTION = lexbase.OPTION
const OPTIONS = lexbase.OPTIONS
const OR = lexbase.OR
const ORDER = lexbase.ORDER
const ORDINALITY = lexbase.ORDINALITY
const OTHERS = lexbase.OTHERS
const OUT = lexbase.OUT
const OUTER = lexbase.OUTER
const OVER = lexbase.OVER
const OVERLAPS = lexbase.OVERLAPS
const OVERLAY = lexbase.OVERLAY
const OWNED = lexbase.OWNED
const OWNER = lexbase.OWNER
const PARENT = lexbase.PARENT
const PARTIAL = lexbase.PARTIAL
const PARTITION = lexbase.PARTITION
const PARTITIONS = lexbase.PARTITIONS
const PASSWORD = lexbase.PASSWORD
const PAUSE = lexbase.PAUSE
const PAUSED = lexbase.PAUSED
const PHYSICAL = lexbase.PHYSICAL
const PLACEHOLDER = lexbase.PLACEHOLDER
const PLACEMENT = lexbase.PLACEMENT
const PLACING = lexbase.PLACING
const PLAN = lexbase.PLAN
const PLANS = lexbase.PLANS
const POINT = lexbase.POINT
const POINTM = lexbase.POINTM
const POINTZ = lexbase.POINTZ
const POINTZM = lexbase.POINTZM
const POLYGON = lexbase.POLYGON
const POLYGONM = lexbase.POLYGONM
const POLYGONZ = lexbase.POLYGONZ
const POLYGONZM = lexbase.POLYGONZM
const POSITION = lexbase.POSITION
const POSTFIXOP = lexbase.POSTFIXOP
const PRECEDING = lexbase.PRECEDING
const PRECISION = lexbase.PRECISION
const PREPARE = lexbase.PREPARE
const PRESERVE = lexbase.PRESERVE
const PRIMARY = lexbase.PRIMARY
const PRIOR = lexbase.PRIOR
const PRIORITY = lexbase.PRIORITY
const PRIVILEGES = lexbase.PRIVILEGES
const PROCEDURAL = lexbase.PROCEDURAL
const PUBLIC = lexbase.PUBLIC
const PUBLICATION = lexbase.PUBLICATION
const QUERIES = lexbase.QUERIES
const QUERY = lexbase.QUERY
const RANGE = lexbase.RANGE
const RANGES = lexbase.RANGES
const READ = lexbase.READ
const REAL = lexbase.REAL
const REASON = lexbase.REASON
const REASSIGN = lexbase.REASSIGN
const RECURRING = lexbase.RECURRING
const RECURSIVE = lexbase.RECURSIVE
const REF = lexbase.REF
const REFERENCES = lexbase.REFERENCES
const REFRESH = lexbase.REFRESH
const REGCLASS = lexbase.REGCLASS
const REGIMATCH = lexbase.REGIMATCH
const REGION = lexbase.REGION
const REGIONAL = lexbase.REGIONAL
const REGIONS = lexbase.REGIONS
const REGNAMESPACE = lexbase.REGNAMESPACE
const REGPROC = lexbase.REGPROC
const REGPROCEDURE = lexbase.REGPROCEDURE
const REGROLE = lexbase.REGROLE
const REGTYPE = lexbase.REGTYPE
const REINDEX = lexbase.REINDEX
const RELATIVE = lexbase.RELATIVE
const RELEASE = lexbase.RELEASE
const RELOCATE = lexbase.RELOCATE
const REMOVE_PATH = lexbase.REMOVE_PATH
const RENAME = lexbase.RENAME
const REPEATABLE = lexbase.REPEATABLE
const REPLACE = lexbase.REPLACE
const REPLICATION = lexbase.REPLICATION
const RESET = lexbase.RESET
const RESET_ALL = lexbase.RESET_ALL
const RESTORE = lexbase.RESTORE
const RESTRICT = lexbase.RESTRICT
const RESTRICTED = lexbase.RESTRICTED
const RESUME = lexbase.RESUME
const RETRY = lexbase.RETRY
const RETURNING = lexbase.RETURNING
const REVISION_HISTORY = lexbase.REVISION_HISTORY
const REVOKE = lexbase.REVOKE
const RIGHT = lexbase.RIGHT
const ROLE = lexbase.ROLE
const ROLES = lexbase.ROLES
const ROLE_ALL = lexbase.ROLE_ALL
const ROLLBACK = lexbase.ROLLBACK
const ROLLUP = lexbase.ROLLUP
const ROUTINES = lexbase.ROUTINES
const ROW = lexbase.ROW
const ROWS = lexbase.ROWS
const RSHIFT = lexbase.RSHIFT
const RULE = lexbase.RULE
const RUNNING = lexbase.RUNNING
const SAVEPOINT = lexbase.SAVEPOINT
const SCANS = lexbase.SCANS
const SCATTER = lexbase.SCATTER
const SCHEDULE = lexbase.SCHEDULE
const SCHEDULES = lexbase.SCHEDULES
const SCHEMA = lexbase.SCHEMA
const SCHEMAS = lexbase.SCHEMAS
const SCONST = lexbase.SCONST
const SCROLL = lexbase.SCROLL
const SCRUB = lexbase.SCRUB
const SEARCH = lexbase.SEARCH
const SECOND = lexbase.SECOND
const SELECT = lexbase.SELECT
const SEQUENCE = lexbase.SEQUENCE
const SEQUENCES = lexbase.SEQUENCES
const SERIALIZABLE = lexbase.SERIALIZABLE
const SERVER = lexbase.SERVER
const SESSION = lexbase.SESSION
const SESSIONS = lexbase.SESSIONS
const SESSION_USER = lexbase.SESSION_USER
const SET = lexbase.SET
const SETS = lexbase.SETS
const SETTING = lexbase.SETTING
const SETTINGS = lexbase.SETTINGS
const SHARE = lexbase.SHARE
const SHOW = lexbase.SHOW
const SIMILAR = lexbase.SIMILAR
const SIMPLE = lexbase.SIMPLE
const SKIP = lexbase.SKIP
const SKIP_LOCALITIES_CHECK = lexbase.SKIP_LOCALITIES_CHECK
const SKIP_MISSING_FOREIGN_KEYS = lexbase.SKIP_MISSING_FOREIGN_KEYS
const SKIP_MISSING_SEQUENCES = lexbase.SKIP_MISSING_SEQUENCES
const SKIP_MISSING_SEQUENCE_OWNERS = lexbase.SKIP_MISSING_SEQUENCE_OWNERS
const SKIP_MISSING_VIEWS = lexbase.SKIP_MISSING_VIEWS
const SMALLINT = lexbase.SMALLINT
const SMALLSERIAL = lexbase.SMALLSERIAL
const SNAPSHOT = lexbase.SNAPSHOT
const SOME = lexbase.SOME
const SPLIT = lexbase.SPLIT
const SQL = lexbase.SQL
const SQLLOGIN = lexbase.SQLLOGIN
const SQRT = lexbase.SQRT
const START = lexbase.START
const STATE = lexbase.STATE
const STATEMENTS = lexbase.STATEMENTS
const STATISTICS = lexbase.STATISTICS
const STATUS = lexbase.STATUS
const STDIN = lexbase.STDIN
const STORAGE = lexbase.STORAGE
const STORE = lexbase.STORE
const STORED = lexbase.STORED
const STORING = lexbase.STORING
const STREAM = lexbase.STREAM
const STRICT = lexbase.STRICT
const STRING = lexbase.STRING
const SUBSCRIPTION = lexbase.SUBSCRIPTION
const SUBSTRING = lexbase.SUBSTRING
const SUPER = lexbase.SUPER
const SURVIVAL = lexbase.SURVIVAL
const SURVIVE = lexbase.SURVIVE
const SYMMETRIC = lexbase.SYMMETRIC
const SYNTAX = lexbase.SYNTAX
const SYSTEM = lexbase.SYSTEM
const TABLE = lexbase.TABLE
const TABLES = lexbase.TABLES
const TABLESPACE = lexbase.TABLESPACE
const TEMP = lexbase.TEMP
const TEMPLATE = lexbase.TEMPLATE
const TEMPORARY = lexbase.TEMPORARY
const TENANT = lexbase.TENANT
const TENANTS = lexbase.TENANTS
const TENANT_ALL = lexbase.TENANT_ALL
const TESTING_RELOCATE = lexbase.TESTING_RELOCATE
const TEXT = lexbase.TEXT
const THEN = lexbase.THEN
const THROTTLING = lexbase.THROTTLING
const TIES = lexbase.TIES
const TIME = lexbase.TIME
const TIMESTAMP = lexbase.TIMESTAMP
const TIMESTAMPTZ = lexbase.TIMESTAMPTZ
const TIMETZ = lexbase.TIMETZ
const TO = lexbase.TO
const TRACE = lexbase.TRACE
const TRACING = lexbase.TRACING
const TRAILING = lexbase.TRAILING
const TRANSACTION = lexbase.TRANSACTION
const TRANSACTIONS = lexbase.TRANSACTIONS
const TRANSFER = lexbase.TRANSFER
const TREAT = lexbase.TREAT
const TRIGGER = lexbase.TRIGGER
const TRIM = lexbase.TRIM
const TRUE = lexbase.TRUE
const TRUNCATE = lexbase.TRUNCATE
const TRUSTED = lexbase.TRUSTED
const TYPE = lexbase.TYPE
const TYPEANNOTATE = lexbase.TYPEANNOTATE
const TYPECAST = lexbase.TYPECAST
const TYPES = lexbase.TYPES
const UMINUS = lexbase.UMINUS
const UNBOUNDED = lexbase.UNBOUNDED
const UNCOMMITTED = lexbase.UNCOMMITTED
const UNION = lexbase.UNION
const UNIQUE = lexbase.UNIQUE
const UNKNOWN = lexbase.UNKNOWN
const UNLOGGED = lexbase.UNLOGGED
const UNSET = lexbase.UNSET
const UNSPLIT = lexbase.UNSPLIT
const UNTIL = lexbase.UNTIL
const UPDATE = lexbase.UPDATE
const UPSERT = lexbase.UPSERT
const USE = lexbase.USE
const USER = lexbase.USER
const USERS = lexbase.USERS
const USER_ALL = lexbase.USER_ALL
const USING = lexbase.USING
const UUID = lexbase.UUID
const VALID = lexbase.VALID
const VALIDATE = lexbase.VALIDATE
const VALUE = lexbase.VALUE
const VALUES = lexbase.VALUES
const VARBIT = lexbase.VARBIT
const VARCHAR = lexbase.VARCHAR
const VARIADIC = lexbase.VARIADIC
const VARYING = lexbase.VARYING
const VIEW = lexbase.VIEW
const VIEWACTIVITY = lexbase.VIEWACTIVITY
const VIEWACTIVITYREDACTED = lexbase.VIEWACTIVITYREDACTED
const VIEWCLUSTERSETTING = lexbase.VIEWCLUSTERSETTING
const VIRTUAL = lexbase.VIRTUAL
const VISIBLE = lexbase.VISIBLE
const VOTERS = lexbase.VOTERS
const WHEN = lexbase.WHEN
const WHERE = lexbase.WHERE
const WINDOW = lexbase.WINDOW
const WITH = lexbase.WITH
const WITHIN = lexbase.WITHIN
const WITHOUT = lexbase.WITHOUT
const WITH_LA = lexbase.WITH_LA
const WORK = lexbase.WORK
const WRITE = lexbase.WRITE
const YEAR = lexbase.YEAR
const ZONE = lexbase.ZONE
Variables ¶
var AllHelp = func(h map[string]HelpMessageBody) string { cmds := make(map[string][]string) for c, details := range h { if details.Category == "" { continue } cmds[details.Category] = append(cmds[details.Category], c) } // Ensure the result is deterministic. var categories []string for c, l := range cmds { categories = append(categories, c) sort.Strings(l) } sort.Strings(categories) // Compile the final help index. var buf bytes.Buffer w := tabwriter.NewWriter(&buf, 0, 0, 1, ' ', 0) for _, cat := range categories { fmt.Fprintf(w, "%s:\n", strings.Title(cat)) for _, item := range cmds[cat] { fmt.Fprintf(w, "\t\t%s\t%s\n", item, h[item].ShortDescription) } fmt.Fprintln(w) } _ = w.Flush() return buf.String() }(helpMessages)
AllHelp contains an overview of all statements with help messages. For example, displayed in the CLI shell with \h without additional parameters.
var HelpMessages = func(h map[string]HelpMessageBody) map[string]HelpMessageBody { appendSeeAlso := func(newItem, prevItems string) string { if prevItems != "" { return newItem + "\n " + prevItems } return newItem } reformatSeeAlso := func(seeAlso string) string { return strings.Replace( strings.Replace(seeAlso, ", ", "\n ", -1), "WEBDOCS", "", -1) } srcMsg := h["<SOURCE>"] srcMsg.SeeAlso = reformatSeeAlso(strings.TrimSpace(srcMsg.SeeAlso)) selectMsg := h["<SELECTCLAUSE>"] selectMsg.SeeAlso = reformatSeeAlso(strings.TrimSpace(selectMsg.SeeAlso)) for k, m := range h { m = h[k] m.ShortDescription = strings.TrimSpace(m.ShortDescription) m.Text = strings.TrimSpace(m.Text) m.SeeAlso = strings.TrimSpace(m.SeeAlso) if strings.Contains(m.Text, "<source>") && k != "<SOURCE>" { m.Text = strings.TrimSpace(m.Text) + "\n\n" + strings.TrimSpace(srcMsg.Text) m.SeeAlso = appendSeeAlso(srcMsg.SeeAlso, m.SeeAlso) } if strings.Contains(m.Text, "<selectclause>") && k != "<SELECTCLAUSE>" { m.Text = strings.TrimSpace(m.Text) + "\n\n" + strings.TrimSpace(selectMsg.Text) m.SeeAlso = appendSeeAlso(selectMsg.SeeAlso, m.SeeAlso) } if strings.Contains(m.Text, "<tablename>") { m.SeeAlso = appendSeeAlso("SHOW TABLES", m.SeeAlso) } m.SeeAlso = reformatSeeAlso(m.SeeAlso) h[k] = m } return h }(helpMessages)
HelpMessages is the registry of all help messages, keyed by the top-level statement that they document. The key is intended for use via the \h client-side command.
Functions ¶
func GetTypeFromValidSQLSyntax ¶
func GetTypeFromValidSQLSyntax(sql string) (tree.ResolvableTypeReference, error)
GetTypeFromValidSQLSyntax retrieves a type from its SQL syntax. The caller is responsible for guaranteeing that the type expression is valid SQL. This includes verifying that complex identifiers are enclosed in double quotes, etc.
func GetTypeReferenceFromName ¶
func GetTypeReferenceFromName(typeName tree.Name) (tree.ResolvableTypeReference, error)
GetTypeReferenceFromName turns a type name into a type reference. This supports only “simple” (single-identifier) references to built-in types, when the identifer has already been parsed away from the input SQL syntax.
func NakedIntTypeFromDefaultIntSize ¶
NakedIntTypeFromDefaultIntSize given the size in bits or bytes (preferred) of how a "naked" INT type should be parsed returns the corresponding integer type.
func ParseExpr ¶
ParseExpr parses a SQL scalar expression. The caller is responsible for ensuring that the input is, in fact, a valid SQL scalar expression — the results are undefined if the string contains invalid SQL syntax.
func ParseExprWithInt ¶
ParseExprWithInt parses a SQL scalar expression, using the given type when INT is used as type name in the SQL syntax. The caller is responsible for ensuring that the input is, in fact, a valid SQL scalar expression — the results are undefined if the string contains invalid SQL syntax.
func ParseExprs ¶
ParseExprs parses a comma-delimited sequence of SQL scalar expressions. The caller is responsible for ensuring that the input is, in fact, a comma-delimited sequence of SQL scalar expressions — the results are undefined if the string contains invalid SQL syntax.
func ParseQualifiedTableName ¶
ParseQualifiedTableName parses a possibly qualified table name. The table name must contain one or more name parts, using the full input SQL syntax: each name part containing special characters, or non-lowercase characters, must be enclosed in double quote. The name may not be an invalid table name (the caller is responsible for guaranteeing that only valid table names are provided as input).
func ParseTableName ¶
func ParseTableName(sql string) (*tree.UnresolvedObjectName, error)
ParseTableName parses a table name. The table name must contain one or more name parts, using the full input SQL syntax: each name part containing special characters, or non-lowercase characters, must be enclosed in double quote. The name may not be an invalid table name (the caller is responsible for guaranteeing that only valid table names are provided as input).
func RunShowSyntax ¶
func RunShowSyntax( ctx context.Context, stmt string, report func(ctx context.Context, field, msg string), reportErr func(ctx context.Context, err error), )
RunShowSyntax analyzes the syntax and reports its structure as data for the client. Even an error is reported as data.
Since errors won't propagate to the client as an error, but as a result, the usual code path to capture and record errors will not be triggered. Instead, the caller can pass a reportErr closure to capture errors instead. May be nil.
func SplitFirstStatement ¶
SplitFirstStatement returns the length of the prefix of the string up to and including the first semicolon that separates statements. If there is no including the first semicolon that separates statements. If there is no semicolon, returns ok=false.
Types ¶
type HelpMessage ¶
type HelpMessage struct {
// Command is set if the message is about a statement.
Command string
// Function is set if the message is about a built-in function.
Function string
// HelpMessageBody contains the details of the message.
HelpMessageBody
}
HelpMessage describes a contextual help message.
func (*HelpMessage) Format ¶
func (h *HelpMessage) Format(w io.Writer)
Format prints out details about the message onto the specified output stream.
func (*HelpMessage) String ¶
func (h *HelpMessage) String() string
String implements the fmt.String interface.
type HelpMessageBody ¶
HelpMessageBody defines the body of a help text. The messages are structured to facilitate future help navigation functionality.
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser wraps a scanner, parser and other utilities present in the parser package.
func (*Parser) Parse ¶
func (p *Parser) Parse(sql string) (Statements, error)
Parse parses the sql and returns a list of statements.
func (*Parser) ParseWithInt ¶
ParseWithInt parses a sql statement string and returns a list of Statements. The INT token will result in the specified TInt type.
type Statement ¶
type Statement struct {
// AST is the root of the AST tree for the parsed statement.
AST tree.Statement
// SQL is the original SQL from which the statement was parsed. Note that this
// is not appropriate for use in logging, as it may contain passwords and
// other sensitive data.
SQL string
// NumPlaceholders indicates the number of arguments to the statement (which
// are referenced through placeholders). This corresponds to the highest
// argument position (i.e. the x in "$x") that appears in the query.
//
// Note: where there are "gaps" in the placeholder positions, this number is
// based on the highest position encountered. For example, for `SELECT $3`,
// NumPlaceholders is 3. These cases are malformed and will result in a
// type-check error.
NumPlaceholders int
// NumAnnotations indicates the number of annotations in the tree. It is equal
// to the maximum annotation index.
NumAnnotations tree.AnnotationIdx
}
Statement is the result of parsing a single statement. It contains the AST node along with other information.
func ParseOne ¶
ParseOne parses a sql statement string, ensuring that it contains only a single statement, and returns that Statement. ParseOne will always interpret the INT and SERIAL types as 64-bit types, since this is used in various internal-execution paths where we might receive bits of SQL from other nodes. In general,earwe expect that all user-generated SQL has been run through the ParseWithInt() function.
type Statements ¶
type Statements []Statement
Statements is a list of parsed statements.
func Parse ¶
func Parse(sql string) (Statements, error)
Parse parses a sql statement string and returns a list of Statements.
func (Statements) String ¶
func (stmts Statements) String() string
String returns the AST formatted as a string.
func (Statements) StringWithFlags ¶
func (stmts Statements) StringWithFlags(flags tree.FmtFlags) string
StringWithFlags returns the AST formatted as a string (with the given flags).
type TokenString ¶
TokenString is the unit value returned by Tokens.
func Tokens ¶
func Tokens(sql string) (tokens []TokenString, ok bool)
Tokens decomposes the input into lexical tokens.
func TokensIgnoreErrors ¶
func TokensIgnoreErrors(sql string) (tokens []TokenString)
TokensIgnoreErrors decomposes the input into lexical tokens and ignores errors.
Source Files