Lexical Structure
See also:
[ StackQL Resource Hierarchy ] [ Keywords ] [ Data Types ] [ DESCRIBE ]
StackQL’s lexical structure and grammar is modelled upon MySQL’s language implementation (an adaptation of the ANSI SQL-92 standard) with some extensions. StackQL statements are used to query cloud resources (using SELECT grammar) or create, modify or delete infrastructure using standard Data Manipulation Language (DML) statements such as INSERT, UPDATE, REPLACE and DELETE. Additionally, non DML operations such as starting an instance, or getting or putting an object into a bucket in AWS S3 for example are implemented as built-in provider procedures (akin to Stored Procedures in a DBMS). Built-in provider procedures are invoked using the EXEC statement.
StackQL’s SQL domain-specific language allows for declarative as well as procedural infrastructure programming.
Syntax
StackQL operations are comprised of one or more semicolon (;) terminated statements. Statements include keywords, identifiers, parameters and values, an example StackQL statement used to create a 10GB disk in GCP would be:
INSERT INTO google.compute.disks (project, zone, name, sizeGb)
SELECT 'myProject', 'australia-southeast1-a', 'my10GbDisk', 10;
In the above example, INSERT, INTO and SELECT are keywords, google.compute.disks is an identifier, project, zone, name, sizeGb are parameters, and 'myProject', 'australia-southeast1-a', 'my10GbDisk', 10 are values.
Keywords
Keywords are not case sensitive, meaning INSERT and insert are treated equivalently, however they are often capitalized by convention. A complete list of keywords can be found in the Keywords section.
Identifiers
Identifiers are symbols that represent objects in a cloud provider resource hierarchy. Identifiers are made up of multiple parts, more information on identifiers can be found in the StackQL Resource Hierarchy topic.
Parameters and Values
Parameters are specified by the resource; these can be found by using a DESCRIBE statement for a given cloud provider resource. Values are typed scalar or complex objects which map to parameters. For more information on parameters and values, see the DESCRIBE and Data Types topics.
Variables
A dollar-prefixed identifier such as $region dereferences a session variable assigned with SET; it is replaced with the variable's typed value before the statement is planned. A single-quoted '$region' is a string literal. In a FROM clause a $variable resolves to a relation name, and IDENTIFIER($variable) resolves to a column name in expression positions. A double-quoted, dollar-prefixed path such as "$.auth.aws.password" is a runtime configuration target accepted by SET and UNSET. Session variables are available in StackQL v1.0 and later, see Session Variables.
Operators
|| is the string concatenation operator and binds more tightly than comparison operators. OR is boolean disjunction. StackQL releases before v1.0 tokenised || as OR.
Comments
StackQL supports multi-line and in line comments within StackQL statements, examples of comments are shown below:
/* This
Is a
Multiline
Comment
*/
--This is an inline comment