lib/SQL/Abstract/Manual/Specification.pod

   1 =head1 NAME
   2
   3 SQL::Abstract::Manual::Specification
   4
   5 =head1 SYNOPSIS
   6
   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.
  11
  12 =head1 MOTIVATIONS
  13
  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.
  20
  21 =head1 GOALS
  22
  23 The goals for this AST are as follows:
  24
  25 =head2 SQL-specific semantics
  26
  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
  30 as placeholders.
  31
  32 =head2 Perl-specific semantics
  33
  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.
  37
  38 =head2 Whole-lifecycle management
  39
  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.
  45
  46 =head2 Dialect-agnostic usage
  47
  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 API to the AST will provide ways of expressing common
  52 functionality in a common language.  The emitters (objects that follow the
  53 Visitor pattern) will be responsible for converting that common language into
  54 RDBMS-specific SQL.
  55
  56 =head1 AST STRUCTURE
  57
  58 The AST will be a HoA (hash of arrays). The keys to the hash will be the various
  59 clauses of a SQL statement, plus some metadata keys. All metadata keys will be
  60 identifiable as such by being prefixed with an underscore. All keys will be in
  61 lowercase.
  62
  63 =head2 Metadata keys
  64
  65 These are the additional metadata keys that the AST provides for.
  66
  67 =over 4
  68
  69 =item * _query
  70
  71 This denotes what kind of query this AST should be interpreted as.
  72
  73 =item *
  74
  75 =back
  76
  77 =head2 Structural units
  78
  79 Structural units in the AST are supported by loaded components. L<SQL::Abstract>
  80 provides for the following structural units by default:
  81
  82 =head3 Identifier
  83
  84 This is a (potentially) fully canonicalized identifier for a table or column. Is
  85 is of the structure C< [schema][sep][table][sep]column > or
  86 C< [schema][sep]table >.
  87
  88 In the case of a two-element identifier which could be C< table[sep]column > or
  89 C< schema[sep]table >, context will determine which it is. However, the AST
  90 doesn't care which it is, only that it properly parses.
  91
  92 =head3 Constant
  93
  94 A Constant is a Perl scalar. It may either be a String (quoted series of
  95 characters) or a number (unquoted).
  96
  97 =head3 Function
  98
  99 A Function is anything of the form C< name( arglist ) > where C<name> is a
 100 string and C<arglist> is a comma-separated list of Expressions.
 101
 102 Yes, a Subquery is legal as an argument for many functions.
 103
 104 =head3 Subquery
 105
 106 A Subquery is another AST whose _query metadata parameter is set to "SELECT".
 107
 108 Most places that a Subquery can be used would require a single value to be
 109 returned (single column, single row), but that is not something that the AST can
 110 easily enforce. The single-column restriction can possibly be enforced, but the
 111 single-row restriction is much more difficult and, in most cases, probably
 112 impossible.
 113
 114 =head3 Unary Operator
 115
 116 A UnaryOperator takes a single argument on the RHS and is one of the following:
 117
 118 =over 4
 119
 120 =item * C<< NOT >>
 121
 122 =back
 123
 124 =head3 BinaryOperator
 125
 126 A BinaryOperator takes two arguments (one on the LHS and one on the RHS) and is
 127 one of the following:
 128
 129 =over 4
 130
 131 =item * C<< = >>
 132
 133 =item * C<< != >>
 134
 135 =item * C<< > >>
 136
 137 =item * C<< < >>
 138
 139 =item * C<< >= >>
 140
 141 =item * C<< <= >>
 142
 143 =item * C<< IS >>
 144
 145 =item * C<< IS NOT >>
 146
 147 =item * C<< IN >>
 148
 149 =item * C<< NOT IN >>
 150
 151 =back
 152
 153 Note that an operator can comprise of what would be multiple tokens in a normal
 154 parsing effort.
 155
 156 =head3 Expression
 157
 158 An expression can be any one of the following:
 159
 160 =over 4
 161
 162 =item * Constant
 163
 164 =item * Function
 165
 166 =item * Subquery
 167
 168 =item * UnaryOperator Expression
 169
 170 =item * Expression BinaryOperator Expression
 171
 172 =back
 173
 174 =head2 SQL clauses
 175
 176 The expected clauses are (name and structure):
 177
 178 =head3 select
 179
 180 This corresponds to the SELECT clause of a SELECT statement. It maps to a comma-
 181 separated list of the following construct C< Expression [ [ AS ] String ] >
 182 (where the [] indicate optional items).
 183
 184 =head3 tables
 185
 186 This is a list of tables that this clause is affecting. It corresponds to the
 187 FROM clause in a SELECT statement and the UPDATE/DELETE clauses in those
 188 respective statements. Depending on the _query metadata entry, the appropriate
 189 clause name will be used.
 190
 191 The tables clause has several RDBMS-specific variations. The AST will support
 192 all of them and it is up to the Visitor object constructing the actual SQL to
 193 validate and/or use what is provided as appropriate.
 194
 195 A table clause is composed as follows:
 196
 197   TableIdentifier := Identifier [ [ AS ] String ]
 198   JoinType := < LEFT|RIGHT [ OUTER ] > | < INNER >
 199
 200   TableIdentifier
 201   [
 202       < , TableIdentifier >
 203     | <
 204         [ JoinType ] JOIN TableIdentifier
 205         [
 206             < USING ( Identifier [ , Identifier ] ) >
 207           | < ON [ ( ] Expression [ , Expression ] [ ) ] >
 208         ]
 209       >
 210   ]*
 211
 212 Additionally, where aliases are provided for in the TableIdentifier, those
 213 aliases must be used as the tablename in subsequent Identifiers that identify a
 214 column of that table.
 215
 216 =head3 where
 217
 218 =head3 set
 219
 220 =head3 values
 221
 222 =head3 orderby
 223
 224 =head3 groupby
 225
 226 =head3 rows
 227
 228 =head3 for
 229
 230 =head3
 231
 232 =head1 AUTHORS
 233
 234 robkinyon: Rob Kinyon <rkinyon@cpan.org>
 235
 236 =head1 LICENSE
 237
 238 You may distribute this code under the same terms as Perl itself.
 239
 240 =cut