From: Matt S Trout Date: Mon, 30 Sep 2019 19:51:47 +0000 (+0000) Subject: doc select and update queries X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=5c04ab130a3e1147db69b2f523edea55e52f63ea;p=scpubgit%2FQ-Branch.git doc select and update queries --- diff --git a/lib/SQL/Abstract/Reference.pm b/lib/SQL/Abstract/Reference.pm index 771d222..41d95d0 100644 --- a/lib/SQL/Abstract/Reference.pm +++ b/lib/SQL/Abstract/Reference.pm @@ -912,4 +912,122 @@ Expands to a bind node with the currently applicable column name if known: foo = ? [ 3 ] +=head1 Query Types + +=head2 select + +A select node accepts select, from, where and order_by clauses. + +The select clause is expanded as a list expression with a -ident default: + + # expr + { -select => { _ => [ 'foo', 'bar', { -count => 'baz' } ] } } + + # aqt + { -select => { select => { -op => [ + ',', { -ident => [ 'foo' ] }, { -ident => [ 'bar' ] }, + { -func => [ 'count', { -ident => [ 'baz' ] } ] }, + ] } } } + + # query + SELECT foo, bar, COUNT(baz) + [] + +The from clause is expanded as a list expression with a -ident default: + + # expr + { -select => { + from => [ 'schema1.table1', { -ident => [ 'schema2', 'table2' ] } ] + } } + + # aqt + { -select => { from => { -from_list => [ + { -ident => [ 'schema1', 'table1' ] }, + { -ident => [ 'schema2', 'table2' ] }, + ] } } } + + # query + FROM schema1.table1, schema2.table2 + [] + +The where clause is expanded as a plain expression: + + # expr + { -select => { where => { foo => 3 } } } + + # aqt + { -select => { where => { + -op => [ '=', { -ident => [ 'foo' ] }, { -bind => [ 'foo', 3 ] } ] + } } } + + # query + WHERE foo = ? + [ 3 ] + +The order_by clause expands as a list expression at top level, but a hashref +element may be either an expr or a hashpair with key -asc or -desc to indicate +an order by direction: + + # expr + { -select => + { order_by => [ 'foo', { -desc => 'bar' }, { -max => 'baz' } ] } + } + + # aqt + { -select => { order_by => { -op => [ + ',', { -ident => [ 'foo' ] }, { + -op => [ ',', { -op => [ 'desc', { -ident => [ 'bar' ] } ] } ] + }, { -func => [ 'max', { -ident => [ 'baz' ] } ] }, + ] } } } + + # query + ORDER BY foo, bar DESC, MAX(baz) + [] + +=head2 update + +An update node accepts update/target (either may be used at expansion time), +set, where, and returning clauses. + +The target clause is expanded with an ident default. + +The set clause (if not already a list expr) is expanded as a hashref where +the keys are identifiers to be set and the values are exprs/values. + +The where clauses is expanded as a normal expr. + +The returning clause is expanded as a list expr with an ident default. + + # expr + { -update => { + _ => 'foo', + returning => [ 'id', 'baz' ], + set => { bar => 3, baz => { baz => { '+' => 1 } } }, + where => { -not => { -ident => 'quux' } }, + } } + + # aqt + { -update => { + returning => + { + -op => [ ',', { -ident => [ 'id' ] }, { -ident => [ 'baz' ] } ] + }, + set => { -op => [ + ',', { -op => + [ '=', { -ident => [ 'bar' ] }, { -bind => [ 'bar', 3 ] } ] + }, { -op => [ + '=', { -ident => [ 'baz' ] }, { -op => [ + '+', { -ident => [ 'baz' ] }, + { -bind => [ 'baz', 1 ] }, + ] }, + ] }, + ] }, + target => { -from_list => [ { -ident => [ 'foo' ] } ] }, + where => { -op => [ 'not', { -ident => [ 'quux' ] } ] }, + } } + + # query + UPDATE foo SET bar = ?, baz = baz + ? WHERE (NOT quux) RETURNING id, baz + [ 3, 1 ] + =cut