Top | ![]() |
![]() |
![]() |
![]() |
gboolean | auto-clean | Read / Write |
guint | cond-serial | Read |
guint | field-serial | Read |
gpointer | really-all-fields | Read |
guint | target-serial | Read |
void | condition-changed | Run First |
void | join-added | Run First |
void | join-removed | Run First |
void | join-updated | Run First |
void | sub-query-added | Run First |
void | sub-query-removed | Run First |
void | sub-query-updated | Run First |
void | target-added | Run First |
void | target-removed | Run First |
void | target-updated | Run First |
void | type-changed | Run First |
A GdaQuery object represents any query (of any type, see the GdaQueryType enum), and can contain some variables to be set before the query can be executed (also refered to as place holders or query parameters). As there is no standard about how to represent variables in SQL statements (there are several notations depending on the database SQL dialect:":<name>", "$<nnn>", "!<nnn>", etc), libgda implements its own different and more exhaustive way of defining variables, which is described in this section.
When executed, and depending on the database provider, a query will be converted to a prepared statement which saves some execution time as SQL parsing needs to be done only on the first execution.
GdaQuery * gda_query_new_copy (GdaQuery *orig
,GHashTable *replacements
);
Copy constructor
GdaQuery * gda_query_new_from_sql (GdaDict *dict
,const gchar *sql
,GError **error
);
Creates a new GdaQuery object and fills its structure by parsing the sql
. If the parsing failed,
then the returned query is of type GDA_QUERY_TYPE_NON_PARSED_SQL.
To be parsed successfully, the expected SQL must respect the SQL standard; some extensions have been added to be able to define variables within the SQL statement. See the introduction to the GdaQuery for more information.
The error
is set only if the SQL statement parsing produced an error; there is always a new GdaQuery
object which is returned.
void gda_query_declare_condition (GdaQuery *query
,GdaQueryCondition *cond
);
Declares the existence of a new condition to query
. All the GdaQueryCondition objects MUST
be declared to the corresponding GdaQuery object for the library to work correctly.
Once cond
has been declared, query
does not hold any reference to cond
.
This functions is called automatically from each gda_query_condition_new* function, and it should not be necessary to call it except for classes extending the GdaQueryCondition class.
void gda_query_undeclare_condition (GdaQuery *query
,GdaQueryCondition *cond
);
Explicitely ask query
to forget about the existence of cond
. This function is used by the
GdaQueryCondition implementation, and should not be called directly
void gda_query_set_query_type (GdaQuery *query
,GdaQueryType type
);
Sets the type of query
GdaQueryType
gda_query_get_query_type (GdaQuery *query
);
Get the type of a query
const gchar *
gda_query_get_query_type_string (GdaQuery *query
);
Get the type of a query as a human readable string
gboolean
gda_query_is_select_query (GdaQuery *query
);
Tells if query
is a SELECTION query (a simple SELECT, UNION, INTERSECT or EXCEPT);
gboolean
gda_query_is_insert_query (GdaQuery *query
);
Tells if query
is a INSERT query.
gboolean
gda_query_is_update_query (GdaQuery *query
);
Tells if query
is a UPDATE query.
gboolean
gda_query_is_delete_query (GdaQuery *query
);
Tells if query
is a DELETE query.
gboolean gda_query_is_well_formed (GdaQuery *query
,GdaParameterList *context
,GError **error
);
Tells if query
is well formed, and if context
is not NULL
, also tells if rendering to
SQL can be done without error
query |
a GdaQuery object |
|
context |
a GdaParameterList obtained using |
|
error |
a place to store errors, or |
void gda_query_set_sql_text (GdaQuery *query
,const gchar *sql
,GError **error
);
Defines query
's contents from an SQL statement. The SQL text is parsed and the internal query structured
is built from that; the query type is also set. If the SQL text cannot be parsed, then the internal structure
of the query is emptied and the query type is set to GDA_QUERY_TYPE_NON_PARSED_SQL.
To be parsed successfully, the expected SQL must respect the SQL standard; some extensions have been added to be able to define variables within the SQL statement. See the introduction to the GdaQuery for more information.
if sql
contains in fact several SQL statements (separated by ';'), then
only the first statement will be taken into account, and error
's code will be
set to GDA_QUERY_MULTIPLE_STATEMENTS_ERROR.
query |
a # GdaQuery object |
|
sql |
the SQL statement |
|
error |
location to store parsing error, or |
gchar *
gda_query_get_sql_text (GdaQuery *query
);
Obtain a new string representing the SQL version of the query.
WARNING: the returned SQL statement may contain some extensions which allow for the definition of variables (see the introduction to the GdaQuery for more information). As such the returned SQL cannot be executed as it may provoque errors. To get an executable statement, use the GdaRenderer interface's methods.
GSList *
gda_query_get_parameters (GdaQuery *query
);
Get a list of parameters which the query accepts.
GdaParameterList *
gda_query_get_parameter_list (GdaQuery *query
);
Like the gda_query_get_parameters()
method, get a list of parameters which the query accepts,
except that the parameters are stored within a GdaParameterList object, and can be used as an argument
to the gda_query_execute()
method.
GdaObject * gda_query_execute (GdaQuery *query
,GdaParameterList *params
,gboolean iter_model_only_requested
,GError **error
);
Executes query
and returns GdaDataModel if query
's execution yields to a data set, or a
GdaParameterList object otherwise, or NULL
if an error occurred. You can test the return value
using GObject's introscpection features such as GDA_IS_DATA_MODEL()
or GDA_IS_PARAMETER_LIST()
.
For more information about the returned value, see gda_server_provider_execute_command()
.
query |
the GdaQuery to execute |
|
params |
a GdaParameterList object obtained using |
|
iter_model_only_requested |
set to TRUE if the returned data model will only be accessed using an iterator |
|
error |
a place to store errors, or |
GdaQuery *
gda_query_get_parent_query (GdaQuery *query
);
Get the parent query of query
GdaQueryField * gda_query_get_field_by_ref_field (GdaQuery *query
,GdaQueryTarget *target
,GdaEntityField *ref_field
,GdaQueryFieldState field_state
);
Finds the first GdaQueryField object in query
which represents ref_field
.
The returned object will be a GdaQueryFieldField object which represents ref_field
.
If target
is specified, then the returned field will be linked to that GdaQueryTarget object.
query |
a GdaQuery object |
|
target |
a GdaQueryTarget, or |
|
ref_field |
a GdaEntityField object |
|
field_state |
tells about the status of the requested field, see GdaQueryFieldState |
GdaQueryField * gda_query_get_field_by_param_name (GdaQuery *query
,const gchar *param_name
);
GdaQueryField * gda_query_get_first_field_for_target (GdaQuery *query
,GdaQueryTarget *target
);
Finds the first occurence of a GdaQueryFieldField object whose target is target
in query
GSList *
gda_query_get_sub_queries (GdaQuery *query
);
Get a list of all the sub-queries managed by query
void gda_query_add_param_source (GdaQuery *query
,GdaDataModel *param_source
);
Tells query
that param_source
is a query which potentially will constraint the possible values
of one or more of query
's parameters. This implies that query
keeps a reference on param_source
.
void gda_query_del_param_source (GdaQuery *query
,GdaDataModel *param_source
);
Tells query
that it should no longer take care of param_source
.
The parameters which depend on param_source
will still depend on it, though.
const GSList *
gda_query_get_param_sources (GdaQuery *query
);
Get a list of the parameter source queries that are references as such by query
.
void gda_query_add_sub_query (GdaQuery *query
,GdaQuery *sub_query
);
Add sub_query
to query
. Sub queries are managed by their parent query, and as such they
are destroyed when their parent query is destroyed.
void gda_query_del_sub_query (GdaQuery *query
,GdaQuery *sub_query
);
Removes sub_query
from query
. sub_query
MUST be present within query
.
GSList *
gda_query_get_targets (GdaQuery *query
);
Get a list of all the targets used in query
gboolean gda_query_add_target (GdaQuery *query
,GdaQueryTarget *target
,GError **error
);
Adds a target to query
. A target represents a entity (it can actually be a table,
a view, or another query) which query
will use.
For a SELECT query, the targets appear after the FROM clause. The targets can be joined two by two using GdaQueryJoin objects
For UPDATE, DELETE or INSERT queries, there can be only ONE GdaQueryTarget object which is the one where the data modifications are performed.
For UNION and INTERSECT queries, there is no possible GdaQueryTarget object.
query |
a GdaQuery object |
|
target |
a GdaQueryTarget to add to |
|
error |
location to store error, or |
void gda_query_del_target (GdaQuery *query
,GdaQueryTarget *target
);
Removes target
from query
. target
MUST be present within query
. Warning:
All the joins and fields which depended on target
are also removed.
GdaQueryTarget * gda_query_get_target_by_xml_id (GdaQuery *query
,const gchar *xml_id
);
Get a pointer to a GdaQueryTarget (which must be within query
) using
its XML Id
GdaQueryTarget * gda_query_get_target_by_alias (GdaQuery *query
,const gchar *alias_or_name
);
Get a pointer to a GdaQueryTarget (which must be within query
) using
its alias (if not found then alias_or_name
is interpreted as the target name)
GSList * gda_query_get_target_pkfields (GdaQuery *query
,GdaQueryTarget *target
);
Makes a list of the GdaQueryField objects which represent primary key fields of
the entity represented by target
.
If the entity represented by target
does not have any primary key, or if the
primary key's fields are not present in query
, then the returned value is NULL
.
GSList *
gda_query_get_joins (GdaQuery *query
);
Get a list of all the joins used in query
GdaQueryJoin * gda_query_get_join_by_targets (GdaQuery *query
,GdaQueryTarget *target1
,GdaQueryTarget *target2
);
Find a join in query
which joins the target1
and target2
targets
gboolean gda_query_add_join (GdaQuery *query
,GdaQueryJoin *join
);
Add a join to query
. A join is defined by the two GdaQueryTarget objects it joins and by
a join condition which MUST ONLY make use of fields of the two entities represented by the
targets.
For any given couple of GdaQueryTarget objects, there can exist ONLY ONE GdaQueryJoin which joins the two.
void gda_query_del_join (GdaQuery *query
,GdaQueryJoin *join
);
Removes join
from query
. join
MUST be present within query
.
GdaQueryCondition *
gda_query_get_condition (GdaQuery *query
);
Get the query's associated condition
void gda_query_set_condition (GdaQuery *query
,GdaQueryCondition *cond
);
Sets the query's associated condition; if there was already a query condition, then the old one is trashed first.
Pass NULL
as the cond
argument to remove any query condition
GdaQueryField * gda_query_add_field_from_sql (GdaQuery *query
,const gchar *field
,GError **error
);
Parses field
and if it represents a valid SQL expression for a
field, then add it to query
.
void gda_query_set_order_by_field (GdaQuery *query
,GdaQueryField *field
,gint order
,gboolean ascendant
);
Sets field
to be used in the ORDER BY clause (using the order
and ascendant
attributes) if
order
>= 0. If order
< 0, then field
will not be used in the ORDER BY clause.
query |
a GdaQuery |
|
field |
a GdaQueryField which is in |
|
order |
the order in the list of ORDER BY fields (starts at 0), or -1 |
|
ascendant |
TRUE to sort ascending |
gint gda_query_get_order_by_field (GdaQuery *query
,GdaQueryField *field
,gboolean *ascendant
);
Tells if field
(which MUST be in query
) is part of the ORDER BY clause.
query |
a GdaQuery |
|
field |
a GdaQueryField which is in |
|
ascendant |
if not |
void gda_query_set_results_limit (GdaQuery *query
,gboolean has_limit
,guint limit
,guint offset
);
For a SELECT query, sets the limits for the number of rows returned when the query is executed
query |
a GdaQuery object |
|
has_limit |
if FALSE, then no limit is set ( |
|
limit |
the maximum number of rows returned |
|
offset |
the row offset to start getting rows |
gboolean gda_query_get_results_limit (GdaQuery *query
,guint *limit
,guint *offset
);
For a SELECT query, get the limits for the number of rows returned when the query is executed
GSList *
gda_query_get_all_fields (GdaQuery *query
);
Fetch a list of all the fields of query
: the ones which are visible, and
the ones which are not visible and are not internal query fields.
GdaQueryField * gda_query_get_field_by_sql_naming (GdaQuery *query
,const gchar *sql_name
);
GdaQueryField * gda_query_get_field_by_sql_naming_fields (GdaQuery *query
,const gchar *sql_name
,GSList *fields_list
);
query |
a GdaQuery object |
|
sql_name |
the SQL naming for the requested field |
|
fields_list |
an explicit list of fields to search into |
GSList * gda_query_get_fields_by_target (GdaQuery *query
,GdaQueryTarget *target
,gboolean visible_fields_only
);
Get a list of all the GdaQueryField objects in query
which depent on the existance of
target
.
GSList *
gda_query_get_main_conditions (GdaQuery *query
);
Makes a list of all the conditions (part of the WHERE clause) which
are always verified by query
when it is executed.
Examples: if the WHERE clause is: --> "A and B" then the list will contains {A, B} --> "A and (B or C)" it will contain {A, B or C} --> "A and (B and not C)", it will contain {A, B, not C}
void gda_query_append_condition (GdaQuery *query
,GdaQueryCondition *cond
,gboolean append_as_and
);
Appends the cond
object to query
's condition. If query
does not yet
have any condition, then the result is the same as gda_query_set_condition()
;
otherwise, cond
is added to query
's condition, using the AND operator
if append_as_and
is TRUE, and an OR operator if append_as_and
is FALSE.
query |
a GdaQuery object |
|
cond |
a GdaQueryCondition object |
|
append_as_and |
mode of append if there is already a query condition |
GSList * gda_query_expand_all_field (GdaQuery *query
,GdaQueryTarget *target
);
Converts each visible "target.*" (GdaQueryFieldAll) field into its list of fields. For example "t1.*" becomes "t1.a, t1.b" if table t1 is composed of fields "a" and "b". The original GdaQueryFieldAll field is not removed, but simply rendered non visible.
The returned list must be free'd by the caller using g_slist_free()
.
“auto-clean”
property “auto-clean” gboolean
Determines if the query tries to clean unused objects.
Flags: Read / Write
Default value: TRUE
“condition-changed”
signalvoid user_function (GdaQuery *gdaquery, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“join-added”
signalvoid user_function (GdaQuery *gdaquery, GdaQueryJoin *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“join-removed”
signalvoid user_function (GdaQuery *gdaquery, GdaQueryJoin *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“join-updated”
signalvoid user_function (GdaQuery *gdaquery, GdaQueryJoin *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“sub-query-added”
signalvoid user_function (GdaQuery *gdaquery, GdaQuery *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“sub-query-removed”
signalvoid user_function (GdaQuery *gdaquery, GdaQuery *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“sub-query-updated”
signalvoid user_function (GdaQuery *gdaquery, GdaQuery *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“target-added”
signalvoid user_function (GdaQuery *gdaquery, GdaQueryTarget *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“target-removed”
signalvoid user_function (GdaQuery *gdaquery, GdaQueryTarget *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“target-updated”
signalvoid user_function (GdaQuery *gdaquery, GdaQueryTarget *arg1, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First
“type-changed”
signalvoid user_function (GdaQuery *gdaquery, gpointer user_data)
dbquery |
the object which received the signal. |
|
user_data |
user data set when the signal handler was connected. |
Flags: Run First