Gda.SqlBuilder¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`error_quark` ()
class	`new` (stmt_type)
	`add_case` (test_expr, else_expr, when_array, then_array)
	`add_cond` (op, op1, op2, op3)
	`add_cond_v` (op, op_ids)
	`add_expr_value` (dh, value)
	`add_field_id` (field_name, table_name)
	`add_field_value_as_gvalue` (field_name, value)
	`add_field_value_id` (field_id, value_id)
	`add_function` (func_name, args)
	`add_id` (str)
	`add_param` (param_name, type, nullok)
	`compound_add_sub_select_from_builder` (subselect)
	`compound_set_type` (compound_type)
	`get_statement` ()
	`import_expression_from_builder` (query, expr_id)
	`join_add_field` (join_id, field_name)
	`select_add_field` (field_name, table_name, alias)
	`select_add_target` (table_name, alias)
	`select_add_target_id` (table_id, alias)
	`select_group_by` (expr_id)
	`select_order_by` (expr_id, asc, collation_name)
	`select_set_distinct` (distinct, expr_id)
	`select_set_having` (cond_id)
	`select_set_limit` (limit_count_expr_id, limit_offset_expr_id)
	`set_table` (table_name)
	`set_where` (cond_id)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Name	Type	Access	Description
object	`GObject.Object`	r

Class Details¶

class Gda.SqlBuilder(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Gda.SqlBuilderClass

classmethod error_quark()¶

Return type:: int

classmethod new(stmt_type)¶

Parameters:: stmt_type (Gda.SqlStatementType) – the type of statement to build
Returns:: the newly created object, or None if an error occurred (such as unsupported statement type)
Return type:: Gda.SqlBuilder

Create a new Gda.SqlBuilder object to build Gda.Statement or Gda.SqlStatement objects of type stmt_type

New in version 4.2.

add_case(test_expr, else_expr, when_array, then_array)¶

Parameters:

test_expr (int) – the expression ID representing the test of the CASE, or %0
else_expr (int) – the expression ID representing the ELSE expression, or %0
when_array ([int]) – an array containing each WHEN expression ID, having at least args_size elements
then_array ([int]) – an array containing each THEN expression ID, having at least args_size elements

Returns:

the ID of the new expression, or %0 if there was an error

Return type:

int

Creates a new CASE … WHEN … THEN … ELSE … END expression. The WHEN expression and the THEN expression IDs are taken from the when_array and then_array at the same index, for each index inferior to args_size.

New in version 4.2.

add_cond(op, op1, op2, op3)¶

Parameters:

op (Gda.SqlOperatorType) – type of condition
op1 (int) – the ID of the 1st argument (not 0)
op2 (int) – the ID of the 2nd argument (may be %0 if op needs only one operand)
op3 (int) – the ID of the 3rd argument (may be %0 if op needs only one or two operand)

Returns:

the ID of the new expression, or %0 if there was an error

Return type:

int

Builds a new expression which represents a condition (or operation).

New in version 4.2.

add_cond_v(op, op_ids)¶

Parameters:

op (Gda.SqlOperatorType) – type of condition
op_ids ([int]) – an array of ID for the arguments (not %0)

Returns:

the ID of the new expression, or %0 if there was an error

Return type:

int

Builds a new expression which represents a condition (or operation).

As a side case, if ops_ids_size is 1, then op is ignored, and the returned ID represents op_ids[0] (this avoids any problem for example when op is Gda.SqlOperatorType.AND and there is in fact only one operand).

New in version 4.2.

add_expr_value(dh, value)¶

Parameters:

dh (Gda.DataHandler or None) – deprecated useless argument, just pass None
value (GObject.Value or None) – value to set the expression to, or None or a GDA_TYPE_NULL value to represent an SQL None

Returns:

the ID of the new expression, or %0 if there was an error

Return type:

int

Defines an expression in self which may be reused to build other parts of a statement.

The new expression will contain the value passed as the value argument.

If value's type is a string then it is possible to customize how the value has to be interpreted by passing a specific Gda.DataHandler object as dh. This feature is very rarely used and the dh argument should generally be None.

New in version 4.2.

add_field_id(field_name, table_name)¶

Parameters:

field_name (str) – a field name
table_name (str or None) – a table name, or None

Returns:

the ID of the new expression, or %0 if there was an error

Return type:

int

Defines an expression representing a field in self, which may be reused to build other parts of a statement, for instance as a parameter to Gda.SqlBuilder.add_cond() or Gda.SqlBuilder.add_field_value_id().

Calling this with a None table_name is equivalent to calling Gda.SqlBuilder.add_id().

For SELECT queries, see Gda.SqlBuilder.select_add_field().

New in version 4.2.

add_field_value_as_gvalue(field_name, value)¶

Parameters:

field_name (str) – a field name
value (GObject.Value or None) – value to set the field to, or None or a GDA_TYPE_NULL value to represent an SQL None

Valid only for: INSERT, UPDATE statements.

Specifies that the field represented by field_name will be set to the value identified by value

New in version 4.2.

add_field_value_id(field_id, value_id)¶

Parameters:

field_id (int) – the ID of the field’s name or definition
value_id (int) – the ID of the value to set the field to, or %0

Valid only for: INSERT, UPDATE, SELECT statements

For UPDATE: specifies that the field represented by field_id will be set to the value identified by value_id.
For SELECT: add a selected item to the statement, and if value_id is not %0, then use it as an alias
For INSERT: if field_id represents an SQL identifier (obtained using Gda.SqlBuilder.add_id()): then if value_id is not %0 then specifies that the field represented by field_id will be set to the value identified by value_id, otherwise just specifies a named field to be given a value. If field_id represents a sub SELECT (obtained using gda_sql_builder_add_sub_select()), then this method call defines the sub SELECT from which values to insert are taken.

See also gda_sql_builder_add_field_value() and Gda.SqlBuilder.add_field_value_as_gvalue().

New in version 4.2.

add_function(func_name, args)¶

Parameters:

func_name (str) – the functions’s name
args ([int]) – an array of IDs representing the function’s arguments

Returns:

the ID of the new expression, or %0 if there was an error

Return type:

int

Builds a new expression which represents a function applied to some arguments

New in version 4.2.

add_id(str)¶

Parameters:: str (str) – a string
Returns:: the ID of the new expression, or %0 if there was an error
Return type:: int

Defines an expression representing an identifier in self, which may be reused to build other parts of a statement, for instance as a parameter to Gda.SqlBuilder.add_cond() or Gda.SqlBuilder.add_field_value_id().

The new expression will contain the str literal. For example:

gda_sql_builder_add_id (b, "name")
gda_sql_builder_add_id (b, "date")

will be rendered as SQL as:

name
"date"

because “date” is an SQL reserved keyword.

For fields, see Gda.SqlBuilder.add_field_id().

New in version 4.2.

add_param(param_name, type, nullok)¶

Parameters:

param_name (str) – parameter’s name
type (GObject.GType) – parameter’s type
nullok (bool) – True if the parameter can be set to None

Returns:

the ID of the new expression, or %0 if there was an error

Return type:

int

Defines a parameter in self which may be reused to build other parts of a statement.

The new expression will contain the string literal. For example:

gda_sql_builder_add_param (b, "age", G_TYPE_INT, FALSE) will be rendered as SQL as:

##age::int

New in version 4.2.

compound_add_sub_select_from_builder(subselect)¶

Parameters:: subselect (Gda.SqlBuilder) – a Gda.SqlBuilder, which has to be a SELECT or compound SELECT. This will be copied.

Add a sub select to a COMPOUND statement

New in version 4.2.

compound_set_type(compound_type)¶

Parameters:: compound_type (Gda.SqlStatementCompoundType) – a type of compound

Changes the type of compound which self is making, for a COMPOUND statement

New in version 4.2.

get_statement()¶

Raises:: GLib.Error
Returns:: a new Gda.Statement object, or None if an error occurred
Return type:: Gda.Statement

Creates a new Gda.Statement statement from self's contents.

New in version 4.2.

import_expression_from_builder(query, expr_id)¶

Parameters:

query (Gda.SqlBuilder) – a Gda.SqlBuilder object to get expression from
expr_id (int) – a #GdaSqlBuilderId of the expression in query

Returns:

the ID of the new expression, or %0 if there was an error

Return type:

int

Imports the an expression located in query into self.

New in version 4.2.

join_add_field(join_id, field_name)¶

Parameters:

join_id (int) – the ID of the join to modify (not %0)
field_name (str) – the name of the field to use in the join condition (not None)

Alter a join in a SELECT statement to make its condition use equal field values in the fields named field_name in both tables, via the USING keyword.

New in version 4.2.

select_add_field(field_name, table_name, alias)¶

Parameters:

field_name (str) – a field name
table_name (str or None) – a table name, or None
alias (str or None) – an alias (eg. for the “AS” clause), or None

Returns:

the ID of the added field, or %0 if there was an error

Return type:

int

Valid only for: SELECT statements.

Add a selected selected item to the SELECT statement.

For non-SELECT statements, see Gda.SqlBuilder.add_field_id().

New in version 4.2.

select_add_target(table_name, alias)¶

Parameters:

table_name (str) – the name of the target table
alias (str or None) – the alias to give to the target, or None

Returns:

the ID of the new target, or %0 if there was an error

Return type:

int

Adds a new target to a SELECT statement

New in version 4.2.

select_add_target_id(table_id, alias)¶

Parameters:

table_id (int) – the ID of the expression holding a table reference (not %0)
alias (str or None) – the alias to give to the target, or None

Returns:

the ID of the new (or existing) target, or %0 if there was an error

Return type:

int

Adds a new target to a SELECT statement. If there already exists a target representing the same table and the same alias (or with the same absence of alias) then the same target ID is returned instead of the ID of a new target.

New in version 4.2.

select_group_by(expr_id)¶

Parameters:: expr_id (int) – the ID of the expression to set use in the GROUP BY clause, or 0 to unset any previous GROUP BY clause

Valid only for: SELECT statements

Adds the expr_id expression to the GROUP BY clause’s expressions list

New in version 4.2.

select_order_by(expr_id, asc, collation_name)¶

Parameters:

expr_id (int) – the ID of the expression to use during sorting (not %0)
asc (bool) – True for an ascending sorting
collation_name (str or None) – name of the collation to use when sorting, or None

Adds a new ORDER BY expression to a SELECT statement.

New in version 4.2.

select_set_distinct(distinct, expr_id)¶

Parameters:

distinct (bool) – set to True to have the DISTINCT requirement
expr_id (int) – the ID of the DISTINCT ON expression, or %0 if no expression is to be used. It is ignored if distinct is False.

Defines (if distinct is True) or removes (if distinct is False) a DISTINCT clause for a SELECT statement.

If distinct is True, then the ID of an expression can be specified as the expr_id argument: if not %0, this is the expression used to apply the DISTINCT clause on (the resuting SQL will then usually be “… DISTINCT ON <expression>…”).

New in version 4.2.

select_set_having(cond_id)¶

Parameters:: cond_id (int) – the ID of the expression to set as HAVING condition, or 0 to unset any previous HAVING condition

Valid only for: SELECT statements

Sets the HAVING condition of the statement

New in version 4.2.

select_set_limit(limit_count_expr_id, limit_offset_expr_id)¶

Parameters:

limit_count_expr_id (int) – the ID of the LIMIT expression, or %0
limit_offset_expr_id (int) – the ID of the OFFSET expression, or %0

If limit_count_expr_id is not %0, defines the maximum number of rows in the Gda.DataModel resulting from the execution of the built statement. In this case, the offset from which the rows must be collected can be defined by the limit_offset_expr_id expression if not %0 (note that this feature may not be supported by all the database providers).

If limit_count_expr_id is %0, then removes any LIMIT which may have been imposed by a previous call to this method.

New in version 4.2.

set_table(table_name)¶

Parameters:: table_name (str) – a table name

Valid only for: INSERT, UPDATE, DELETE statements

Sets the name of the table on which the built statement operates.

New in version 4.2.

set_where(cond_id)¶

Parameters:: cond_id (int) – the ID of the expression to set as WHERE condition, or 0 to unset any previous WHERE condition

Valid only for: UPDATE, DELETE, SELECT statements

Sets the WHERE condition of the statement

New in version 4.2.