3 SQL::Abstract::Manual::Specification
7 This discusses the specification for the AST provided by L<SQL::Abstract>. It is
8 meant to describe how the AST is structured, various components provided by
9 L<SQL::Abstract> for use with this AST, how to manipulate the AST, and various
10 uses for the AST once it is generated.
14 L<SQL::Abstract> has been in use for many years. Originally created to handle
15 the where-clause formation found in L<DBIx::Abstract>, it was generalized to
16 manage the creation of any SQL statement through the use of Perl structures.
17 Through the beating it received as the SQL generation syntax for L<DBIx::Class>,
18 various deficiencies were found and a generalized SQL AST was designed. This
19 document describes that AST.
23 The goals for this AST are as follows:
25 =head2 SQL-specific semantics
27 Instead of attempting to be an AST to handle any form of query, this will
28 instead be specialized to manage SQL queries (and queries that map to SQL
29 queries). This means that there will be support for SQL-specific features, such
32 =head2 Perl-specific semantics
34 This AST is meant to be used from within Perl5 only. So, it will take advantage
35 of as many Perl-specific features that make sense to use. No attempt whatosever
36 will be made to make this AST work within any other language, including Perl6.
38 =head2 Whole-lifecycle management
40 Whether a query is built out of whole cloth in one shot or cobbled together from
41 several snippets over the lifetime of a process, this AST will support any way
42 to construct the query. Queries can also be built from other queries, so an
43 UPDATE statement could be used as the basis for a SELECT statement, DELETE
44 statement, or even a DDL statement of some kind.
46 =head2 Dialect-agnostic usage
48 Even though SQL itself has several ANSI specifications (SQL-92 and SQL-99 among
49 them), this only serves as a basis for what a given RDBMS will expect. However,
50 every engine has its own specific extensions and specific ways of handling
51 common features. The AST will provide ways of expressing common functionality in
52 a common language. The emitters (objects that follow the Visitor pattern) will
53 be responsible for converting that common language into RDBMS-specific SQL.
57 The following are the restrictions upon the AST:
61 The AST will only support DML (Data Modelling Language). It will not (currently)
62 support DDL (Data Definition Language). Practically, this means that the only
63 statements supported will be:
77 Additional DML statements may be supported by specific Visitors (such as a
78 MySQL visitor supporting REPLACE INTO). q.v. the relevant sections of this
79 specification for details.
83 There are two major components to SQL::Abstract v2.
89 This is the Abstract Syntax Tree. It is a data structure that represents
90 everything necessary to construct the SQL statement in whatever dialect the
95 This object conforms to the Visitor pattern and is used to generate the SQL
96 represented by the AST. Each dialect will have a different Visitor object. In
97 addition, there will be visitors for at least one of the ANSI specifications.
101 The division of duties between the two components will focus on what the AST
102 can and cannot assume. For example, identifiers do not have 20 components in
103 any dialect, so the AST can validate that. However, determining what
104 constitutes a legal identifier can only be determined by the Visitor object
105 enforcing that dialect's rules.
109 The AST will be a HoHo..oH (hash of hash of ... of hashes). The keys to the
110 outermost hash will be the various clauses of a SQL statement, plus some
111 metadata keys. All metadata keys will be identifiable as such by being prefixed
112 with an underscore. All keys will be in lowercase.
116 These are the additional metadata keys that the AST provides for.
120 This denotes what kind of query this AST should be interpreted as. Different
121 Visitors may accept additional values for _query. For example, a MySQL Visitor
122 may choose to accept 'replace' for REPLACE INTO. If a _query value is
123 unrecognized by the Visitor, the Visitor is expected to throw an error.
125 All Visitors are expected to handle the following values for _query:
131 This is a SELECT statement.
135 This is an INSERT statement.
139 This is an UPDATE statement.
143 This is a DELETE statement.
149 This denotes the version of the AST. Different versions will indicate different
150 capabilities provided. Visitors will choose to respect the _version as needed
153 =head2 Structural units
155 All structural units will be hashes. These hashes will have, at minimum, the
162 This indicates the structural unit that this hash is representing. While this
163 specification provides for standard structural units, different Visitors may
164 choose to accept additional units as desired. If a Visitor encounters a unit it
165 doesn't know how to handle, it is expected to throw an exception.
169 Structural units in the AST are supported by loaded components. L<SQL::Abstract>
170 provides for the following structural units by default:
174 This is a (potentially) fully canonicalized identifier for a elemnt in the
175 query. This element could be a schema, table, or column. The Visitor will
176 determine validity within the context of that SQL dialect. The AST is only
177 responsible for validating that the elements are non-empty Strings.
179 The hash will be structured as follows:
182 name => 'Identifier',
188 If element3 exists, then element2 must exist. element1 must always exist. If a
189 given element exists, then it must be defined and of non-zero length.
191 Visitors are expected to, by default, quote all identifiers according to the SQL
192 dialect's quoting scheme.
196 A Value is a Perl scalar. Depending on the type, a Visitor may be able to make
203 A String is a quoted series of characters. The Visitor is expected to ensure
204 that embedded quotes are properly handled per the SQL dialect's quoting scheme.
208 A Number is an unquoted number in some numeric format.
212 Null is SQL's NULL and corresponds to Perl's C<undef>.
214 =item * BindParameter
216 This corresponds to a value that will be passed in. This value is normally
217 quoted in such a fashion so as to protect against SQL injection attacks. (q.v.
218 L<DBI/quote()> for an example.)
220 BindParameters are normally represented by a '?'.
224 The hash will be structured as follows:
228 subtype => [ 'String' | 'Number' | 'Null' | 'BindParameter' ]
232 The provided subtypes are the ones that all Visitors are expected to support.
233 Visitors may choose to support additional subtypes. Visitors are expected to
234 throw an exception upon encountering an unknown subtype.
238 A Function is anything of the form C<< name( arglist ) >> where C<<name>> is a
239 string and C<arglist> is an ExpressionList.
241 Yes, a Subquery is legal as an argument for many functions. Some example
256 The hash will be structured as follows:
261 arglist => ExpressionList,
264 Functions have a cardinality, or expected number of arguments. Some functions,
265 such as MAX(), have a cardinality of 1. Others, such as IF(), have a cardinality
266 of N, meaning they can have any number of arguments greater than 0. Others, such
267 as NOW(), have a cardinality of 0. Several functions with the same meaning may
268 have a different cardinality in different SQL dialects as different engines may
269 allow different behaviors.
271 As cardinality may differ between dialects, enforcing cardinality is necessarily
276 A Subquery is another AST whose _query metadata parameter is set to "SELECT".
278 Most places that a Subquery can be used would require a single value to be
279 returned (single column, single row), but that is not something that the AST can
280 easily enforce. The single-column restriction may possibly be enforced, but the
281 single-row restriction is much more difficult and, in most cases, probably
284 Subqueries, when expressed in SQL, must be bounded by parentheses.
286 =head3 Unary Operator
288 A UnaryOperator takes a single argument on the RHS. The argument for a
289 UnaryOperator is an Expression.
291 Visitors are expected to support, at minimum, the following operators:
305 The hash for a UnaryOperator is as follows:
308 name => 'UnaryOperator'
309 operator => [ .... ],
310 argument1 => Expression,
313 Visitors may choose to support additional operators. Visitors are expected to
314 throw an exception upon encountering an unknown operator.
316 =head3 BinaryOperator
318 A BinaryOperator takes two arguments (one on the LHS and one on the RHS). The
319 arguments for a BinaryOperator are all Expressions.
321 Visitors are expected to support, at minimum, the following operators:
349 (Note that an operator can comprise of what would be multiple tokens in a normal
352 Visitors may choose to support additional operators. Visitors are expected to
353 throw an exception upon encountering an unknown operator.
355 The hash for a BinaryOperator is as follows:
358 name => 'BinaryOperator'
359 operator => [ .... ],
360 argument1 => Expression,
361 argument2 => Expression,
364 =head3 TrinaryOperator
366 A TrinaryOperator takes three arguments. It generally is composed of two
367 elements with one argument to the LHS, one to the RHS, and a third in the middle
368 of the elements. The arguments for a TrinaryOperator are all Expressions.
370 Visitors are expected to support, at minimum, the following operators:
374 =item * X BETWEEN Y AND Z
378 Visitors may choose to support additional operators. Visitors are expected to
379 throw an exception upon encountering an unknown operator.
381 The hash for a TrinaryOperator is as follows:
384 name => 'TrinaryOperator'
385 operator => [ .... ],
386 argument1 => Expression,
387 argument2 => Expression,
388 argument3 => Expression,
393 An Expression can be any one of the following:
403 =item * UnaryOperator
405 =item * BinaryOperator
407 =item * TrinaryOperator
411 An Expression is a meta-syntactic unit. An "Expression" unit will never appear
412 within the AST. It acts as a junction.
414 =head3 ExpressionList
416 An ExpressionList is a list of Expressions, generally separated by commas
417 (though other separators may be appropriate at times or for different SQL
420 The hash for an ExpressionList is as follows:
423 name => 'ExpressionList',
425 elements => Array of Expressions,
428 An ExpressionList is always rendered in SQL with parentheses around it.
432 These are all the legal and acceptable clauses within the AST that would
433 correpsond to clauses in a SQL statement. Not all clauses are legal within a
434 given RDBMS engine's SQL dialect and some clauses may be required in one and
435 optional in another. Detecting and enforcing those engine-specific restrictions
436 is the responsibility of the Visitor object.
438 The clauses are defined with a yacc-like syntax. The various parts are:
444 This means "defined" and is used to create a new term to be used below.
448 This means optional and indicates that the items within it are optional.
452 This means optional and repeating as many times as desired.
456 This means alternation. It is a binary operator and indicates that either the
457 left or right hand sides may be used, but not both.
461 This is a grouping construct. It means that all elements within this construct
462 are treated together for the purposes of optional, repeating, alternation, etc.
466 The expected clauses are (name and structure):
470 This corresponds to the SELECT clause of a SELECT statement.
472 A select clause unit is an array of one or more SelectComponent units.
474 The hash for a SelectComponent unit is composed as follows:
477 name => 'SelectComponent',
479 [ as => Identifier, ]
482 The 'as' component is optional. Visitors may choose to make it required in
487 This is a list of tables that this clause is affecting. It corresponds to the
488 FROM clause in a SELECT statement and the INSERT INTO/UPDATE/DELETE clauses in
489 those respective statements. Depending on the _query metadata entry, the
490 appropriate clause name will be used.
492 A tables clause unit is an array of one or more TableComponent units.
494 The tables clause has several RDBMS-specific variations. The AST will support
495 all of them and it is up to the Visitor object constructing the actual SQL to
496 validate and/or use what is provided as appropriate.
498 The hash for a TableJoin will be composed as follows:
503 join => < LEFT|RIGHT [ OUTER ] > | INNER | CROSS | ',',
504 [ using => IdentifierList, ]
505 [ on => ExpressionList, ]
508 A TableJoin may not have both a 'using' element and an 'on' element. It may
509 have one of them if the 'join' element is not equal to ',' but doesn't have to.
510 If the 'join' element is equal to ',', then it may not have either a 'using' or
513 The hash for a TableIdentifier will be composed as follows:
517 name => 'TableIdentifier',
518 value => Identifier | SubQuery
519 [ join => TableJoin, ]
520 [ as => Identifier, ]
523 The first TableComponent in a tables clause may not have a join element. All
524 other TableComponent elements that do not have a join element will have a
525 default join element of:
532 The 'as' component is optional. Visitors may choose to make it required in
533 certain situations (such as MySQL requiring an alias for subqueries).
535 Additionally, where aliases are provided for in the TableIdentifier, those
536 aliases must be used as the tablename in subsequent Identifiers that identify a
537 column of that table. This may be enforceable by the AST or the Visitor. But, it
538 is more likely that it will not be.
542 This corresponds to the WHERE clause in a SELECT, UPDATE, or DELETE statement.
544 A where clause is composed as follows:
546 WhereOperator := AND | OR
547 WhereExpression := Expression | Expression WhereOperator Expression
553 This corresponds to the SET clause in an INSERT or UPDATE statement.
555 A set clause is composed as follows:
557 SetComponent := Identifier = Expression
559 SetComponent [ , SetComponent ]*
563 This corresponds to the optional list of columns in an INSERT statement.
565 A columns clause is an IdentifierList and the unit is composed as follows:
574 This corresponds to the VALUES clause in an INSERT statement.
576 A values clause is an ExpressionList and the unit is composed as follows.
583 If there is a columns clause, the number of entries in the values clause must be
584 equal to the number of entries in the columns clause.
588 This corresponds to the ORDER BY clause in a SELECT statement.
590 An orderby clause is composed as follows:
592 OrderByComponent := XXX-TODO-XXX
593 OrderByDirection := ASC | DESC
595 OrderByComponent [ OrderByDirection ]
596 [ , OrderByComponent [ OrderByDirection ] ]*
600 This corresponds to the GROUP BY clause in a SELECT statement.
602 An groupby clause is composed as follows:
604 GroupByComponent := XXX-TODO-XXX
606 GroupByComponent [ , GroupByComponent ]*
610 This corresponds to the clause that is used in some RDBMS engines to limit the
611 number of rows returned by a query. In MySQL, this would be the LIMIT clause.
613 A rows clause is composed as follows:
619 This corresponds to the clause that is used in some RDBMS engines to indicate
620 what locks are to be taken by this SELECT statement.
622 A for clause is composed as follows:
628 This corresponds to the clause that is used in some RDBMS engines to provide for
629 an adjacency-list query.
631 A connectby clause is composed as follows:
633 Identifier, WhereExpression
637 The following are example SQL statements and a possible AST for each one.
645 _ast_version => 0.0001,
648 name => 'SelectComponent',
658 =item * SELECT NOW() AS time FROM dual AS duality
662 _ast_version => 0.0001,
665 name => 'SelectComponent',
671 name => 'Identifier',
678 name => 'TablesComponent',
680 name => 'Identifier',
684 name => 'Identifier',
685 element1 => 'duality',
695 robkinyon: Rob Kinyon C<< <rkinyon@cpan.org> >>
699 You may distribute this code under the same terms as Perl itself.