## GdaQuery GdaQuery — Represents any kind of DML query |

## Synopsis

                        GdaQuery;
    enum                GdaQueryType;
    GdaQuery*           gda_query_new                       (GdaDict *dict);
    GdaQuery*           gda_query_new_copy                  (GdaQuery *orig,
                                                             GHashTable *replacements);
    GdaQuery*           gda_query_new_from_sql              (GdaDict *dict,
                                                             const gchar *sql,
                                                             GError **error);
    void                gda_query_declare_condition         (GdaQuery *query,
                                                             GdaQueryCondition *cond);
    void                gda_query_undeclare_condition       (GdaQuery *query,
                                                             GdaQueryCondition *cond);
    void                gda_query_set_query_type            (GdaQuery *query,
                                                             GdaQueryType type);
    GdaQueryType        gda_query_get_query_type            (GdaQuery *query);
    const gchar*        gda_query_get_query_type_string     (GdaQuery *query);
    gboolean            gda_query_is_select_query           (GdaQuery *query);
    gboolean            gda_query_is_insert_query           (GdaQuery *query);
    gboolean            gda_query_is_update_query           (GdaQuery *query);
    gboolean            gda_query_is_delete_query           (GdaQuery *query);
    gboolean            gda_query_is_well_formed            (GdaQuery *query,
                                                             GdaParameterList *context,
                                                             GError **error);
    void                gda_query_set_sql_text              (GdaQuery *query,
                                                             const gchar *sql,
                                                             GError **error);
    gchar*              gda_query_get_sql_text              (GdaQuery *query);
    GSList*             gda_query_get_parameters            (GdaQuery *query);
    GdaParameterList*   gda_query_get_parameter_list        (GdaQuery *query);
    GdaObject*          gda_query_execute                   (GdaQuery *query,
                                                             GdaParameterList *params,
                                                             gboolean iter_model_only_requested,
                                                             GError **error);
    GdaQuery*           gda_query_get_parent_query          (GdaQuery *query);
    GdaQueryField*      gda_query_get_field_by_ref_field    (GdaQuery *query,
                                                             GdaQueryTarget *target,
                                                             GdaEntityField *ref_field,
                                                             GdaQueryFieldState field_state);
    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);
    GSList*             gda_query_get_sub_queries           (GdaQuery *query);
    void                gda_query_add_param_source          (GdaQuery *query,
                                                             GdaDataModel *param_source);
    void                gda_query_del_param_source          (GdaQuery *query,
                                                             GdaDataModel *param_source);
    const GSList*       gda_query_get_param_sources         (GdaQuery *query);
    void                gda_query_add_sub_query             (GdaQuery *query,
                                                             GdaQuery *sub_query);
    void                gda_query_del_sub_query             (GdaQuery *query,
                                                             GdaQuery *sub_query);
    GSList*             gda_query_get_targets               (GdaQuery *query);
    gboolean            gda_query_add_target                (GdaQuery *query,
                                                             GdaQueryTarget *target,
                                                             GError **error);
    void                gda_query_del_target                (GdaQuery *query,
                                                             GdaQueryTarget *target);
    GdaQueryTarget*     gda_query_get_target_by_xml_id      (GdaQuery *query,
                                                             const gchar *xml_id);
    GdaQueryTarget*     gda_query_get_target_by_alias       (GdaQuery *query,
                                                             const gchar *alias_or_name);
    GSList*             gda_query_get_target_pkfields       (GdaQuery *query,
                                                             GdaQueryTarget *target);
    GSList*             gda_query_get_joins                 (GdaQuery *query);
    GdaQueryJoin*       gda_query_get_join_by_targets       (GdaQuery *query,
                                                             GdaQueryTarget *target1,
                                                             GdaQueryTarget *target2);
    gboolean            gda_query_add_join                  (GdaQuery *query,
                                                             GdaQueryJoin *join);
    void                gda_query_del_join                  (GdaQuery *query,
                                                             GdaQueryJoin *join);
    GdaQueryCondition*  gda_query_get_condition             (GdaQuery *query);
    void                gda_query_set_condition             (GdaQuery *query,
                                                             GdaQueryCondition *cond);
    GdaQueryField*      gda_query_add_field_from_sql        (GdaQuery *query,
                                                             const gchar *field,
                                                             GError **error);
    void                gda_query_set_order_by_field        (GdaQuery *query,
                                                             GdaQueryField *field,
                                                             gint order,
                                                             gboolean ascendant);
    gint                gda_query_get_order_by_field        (GdaQuery *query,
                                                             GdaQueryField *field,
                                                             gboolean *ascendant);
    void                gda_query_set_results_limit         (GdaQuery *query,
                                                             gboolean has_limit,
                                                             guint limit,
                                                             guint offset);
    gboolean            gda_query_get_results_limit         (GdaQuery *query,
                                                             guint *limit,
                                                             guint *offset);
    GSList*             gda_query_get_all_fields            (GdaQuery *query);
    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);
    GSList*             gda_query_get_fields_by_target      (GdaQuery *query,
                                                             GdaQueryTarget *target,
                                                             gboolean visible_fields_only);
    GSList*             gda_query_get_main_conditions       (GdaQuery *query);
    void                gda_query_append_condition          (GdaQuery *query,
                                                             GdaQueryCondition *cond,
                                                             gboolean append_as_and);
    GSList*             gda_query_expand_all_field          (GdaQuery *query,
                                                             GdaQueryTarget *target);
    void                gda_query_order_fields_using_join_conds
                                                            (GdaQuery *query);

## Object Hierarchy

      GObject
       +----GdaObject
             +----GdaQueryObject
                   +----GdaQuery

## Implemented Interfaces

GdaQuery implements GdaXmlStorage, GdaReferer, GdaRenderer and GdaEntity.

## Properties

      "auto-clean"               gboolean              : Read / Write
      "cond-serial"              guint                 : Read
      "field-serial"             guint                 : Read
      "really-all-fields"        gpointer              : Read
      "target-serial"            guint                 : Read

## Signals

      "condition-changed"                              : Run First
      "join-added"                                     : Run First
      "join-removed"                                   : Run First
      "join-updated"                                   : Run First
      "sub-query-added"                                : Run First
      "sub-query-removed"                              : Run First
      "sub-query-updated"                              : Run First
      "target-added"                                   : Run First
      "target-removed"                                 : Run First
      "target-updated"                                 : Run First
      "type-changed"                                   : Run First

## Description

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.

## Details

### GdaQuery

    typedef struct _GdaQuery GdaQuery;

### Warning

`GdaQuery` is deprecated and should not be used in newly-written code.

### enum GdaQueryType

    typedef enum {
            GDA_QUERY_TYPE_SELECT,
    	GDA_QUERY_TYPE_INSERT,
    	GDA_QUERY_TYPE_UPDATE,
    	GDA_QUERY_TYPE_DELETE,
            GDA_QUERY_TYPE_UNION,
            GDA_QUERY_TYPE_INTERSECT,
    	GDA_QUERY_TYPE_EXCEPT,
            GDA_QUERY_TYPE_NON_PARSED_SQL
    } GdaQueryType;

### Warning

`GdaQueryType` is deprecated and should not be used in newly-written code.

### gda_query_new ()

    GdaQuery*           gda_query_new                       (GdaDict *dict);

### Warning

`gda_query_new` is deprecated and should not be used in newly-written code.

Creates a new GdaQuery object

`dict` : | a GdaDict object
Returns : | the new object

### gda_query_new_copy ()

    GdaQuery*           gda_query_new_copy                  (GdaQuery *orig,
                                                             GHashTable *replacements);

### Warning

`gda_query_new_copy` is deprecated and should not be used in newly-written code.

Copy constructor

`orig` : | a GdaQuery to make a copy of
`replacements` : | a hash table to store replacements, or `NULL`
Returns : | a the new copy of `orig`

### gda_query_new_from_sql ()

    GdaQuery*           gda_query_new_from_sql              (GdaDict *dict,
                                                             const gchar *sql,
                                                             GError **error);

### Warning

`gda_query_new_from_sql` is deprecated and should not be used in newly-written code.

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.

`dict` : | a GdaDict object
`sql` : | an SQL statement
`error` : | location to store error, or `NULL`
Returns : | a new GdaQuery

### gda_query_declare_condition ()

    void                gda_query_declare_condition         (GdaQuery *query,
                                                             GdaQueryCondition *cond);

### Warning

`gda_query_declare_condition` is deprecated and should not be used in newly-written code.

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.

`query` : | a GdaQuery object
`cond` : | a GdaQueryCondition object

### gda_query_undeclare_condition ()

    void                gda_query_undeclare_condition       (GdaQuery *query,
                                                             GdaQueryCondition *cond);

### Warning

`gda_query_undeclare_condition` is deprecated and should not be used in newly-written code.

Explicitely ask `query` to forget about the existence of `cond`. This function is used by the GdaQueryCondition implementation, and should not be called directly

`query` : | a GdaQuery object
`cond` : | a GdaQueryCondition object

### gda_query_set_query_type ()

    void                gda_query_set_query_type            (GdaQuery *query,
                                                             GdaQueryType type);

### Warning

`gda_query_set_query_type` is deprecated and should not be used in newly-written code.

Sets the type of `query`

`query` : | a GdaQuery object
`type` : | the new type of query

### gda_query_get_query_type ()

    GdaQueryType        gda_query_get_query_type            (GdaQuery *query);

### Warning

`gda_query_get_query_type` is deprecated and should not be used in newly-written code.

Get the type of a query

`query` : | a GdaQuery object
Returns : | the type of `query`

### gda_query_get_query_type_string ()

    const gchar*        gda_query_get_query_type_string     (GdaQuery *query);

### Warning

`gda_query_get_query_type_string` is deprecated and should not be used in newly-written code.

Get the type of a query as a human readable string

`query` : | a GdaQuery object
Returns : | a string for the type of `query`

### gda_query_is_select_query ()

    gboolean            gda_query_is_select_query           (GdaQuery *query);

### Warning

`gda_query_is_select_query` is deprecated and should not be used in newly-written code.

Tells if `query` is a SELECTION query (a simple SELECT, UNION, INTERSECT or EXCEPT);

`query` : | a # GdaQuery object
Returns : | TRUE if `query` is a selection query

### gda_query_is_insert_query ()

    gboolean            gda_query_is_insert_query           (GdaQuery *query);

### Warning

`gda_query_is_insert_query` is deprecated and should not be used in newly-written code.

Tells if `query` is a INSERT query.

`query` : | a # GdaQuery object
Returns : | TRUE if `query` is an insertion query

### gda_query_is_update_query ()

    gboolean            gda_query_is_update_query           (GdaQuery *query);

### Warning

`gda_query_is_update_query` is deprecated and should not be used in newly-written code.

Tells if `query` is a UPDATE query.

`query` : | a # GdaQuery object
Returns : | TRUE if `query` is an update query

### gda_query_is_delete_query ()

    gboolean            gda_query_is_delete_query           (GdaQuery *query);

### Warning

`gda_query_is_delete_query` is deprecated and should not be used in newly-written code.

Tells if `query` is a DELETE query.

`query` : | a # GdaQuery object
Returns : | TRUE if `query` is an delete query

### gda_query_is_well_formed ()

    gboolean            gda_query_is_well_formed            (GdaQuery *query,
                                                             GdaParameterList *context,
                                                             GError **error);

### Warning

`gda_query_is_well_formed` is deprecated and should not be used in newly-written code.

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 `gda_query_get_parameter_list()`, or `NULL`
`error` : | a place to store errors, or `NULL`
Returns : | FALSE if `query` is not well formed

### gda_query_set_sql_text ()

    void                gda_query_set_sql_text              (GdaQuery *query,
                                                             const gchar *sql,
                                                             GError **error);

### Warning

`gda_query_set_sql_text` is deprecated and should not be used in newly-written code.

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 `NULL`

### gda_query_get_sql_text ()

    gchar*              gda_query_get_sql_text              (GdaQuery *query);

### Warning

`gda_query_get_sql_text` is deprecated and should not be used in newly-written code.

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.

`query` : | a GdaQuery object
Returns : | the new string

### gda_query_get_parameters ()

    GSList*             gda_query_get_parameters            (GdaQuery *query);

### Warning

`gda_query_get_parameters` is deprecated and should not be used in newly-written code.

Get a list of parameters which the query accepts.

`query` : | a GdaQuery object
Returns : | a list of GdaParameter objects (the list and objects must be freed by the caller)

### gda_query_get_parameter_list ()

    GdaParameterList*   gda_query_get_parameter_list        (GdaQuery *query);

### Warning

`gda_query_get_parameter_list` is deprecated and should not be used in newly-written code.

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.

`query` : | a GdaQuery object
Returns : | a new GdaParameterList object, or `NULL` if `query` does not accept any parameter.

### gda_query_execute ()

    GdaObject*          gda_query_execute                   (GdaQuery *query,
                                                             GdaParameterList *params,
                                                             gboolean iter_model_only_requested,
                                                             GError **error);

### Warning

`gda_query_execute` is deprecated and should not be used in newly-written code.

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 `gda_query_get_parameter_list()`
`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 `NULL`
Returns : | a GdaDataModel, a GdaParameterList or `NULL`.

### gda_query_get_parent_query ()

    GdaQuery*           gda_query_get_parent_query          (GdaQuery *query);

### Warning

`gda_query_get_parent_query` is deprecated and should not be used in newly-written code.

Get the parent query of `query`

`query` : | a GdaQuery object
Returns : | the parent query, or NULL if `query` does not have any parent

### gda_query_get_field_by_ref_field ()

    GdaQueryField*      gda_query_get_field_by_ref_field    (GdaQuery *query,
                                                             GdaQueryTarget *target,
                                                             GdaEntityField *ref_field,
                                                             GdaQueryFieldState field_state);

### Warning

`gda_query_get_field_by_ref_field` is deprecated and should not be used in newly-written code.

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 `NULL`
`ref_field` : | a GdaEntityField object
`field_state` : | tells about the status of the requested field, see GdaQueryFieldState
Returns : | a GdaQueryFieldField object or `NULL`

### gda_query_get_field_by_param_name ()

    GdaQueryField*      gda_query_get_field_by_param_name   (GdaQuery *query,
                                                             const gchar *param_name);

### Warning

`gda_query_get_field_by_param_name` is deprecated and should not be used in newly-written code.

`query` : |
`param_name` : |
Returns : |

### gda_query_get_first_field_for_target ()

    GdaQueryField*      gda_query_get_first_field_for_target
                                                            (GdaQuery *query,
                                                             GdaQueryTarget *target);

### Warning

`gda_query_get_first_field_for_target` is deprecated and should not be used in newly-written code.

Finds the first occurence of a GdaQueryFieldField object whose target is `target` in `query`

`query` : | a GdaQuery object
`target` : |
Returns : | the requested field, or `NULL`

### gda_query_get_sub_queries ()

    GSList*             gda_query_get_sub_queries           (GdaQuery *query);

### Warning

`gda_query_get_sub_queries` is deprecated and should not be used in newly-written code.

Get a list of all the sub-queries managed by `query`

`query` : | a GdaQuery object
Returns : | a new list of the sub-queries

### gda_query_add_param_source ()

    void                gda_query_add_param_source          (GdaQuery *query,
                                                             GdaDataModel *param_source);

### Warning

`gda_query_add_param_source` is deprecated and should not be used in newly-written code.

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`.

`query` : | a GdaQuery object
`param_source` : | a GdaDataModel object

### gda_query_del_param_source ()

    void                gda_query_del_param_source          (GdaQuery *query,
                                                             GdaDataModel *param_source);

### Warning

`gda_query_del_param_source` is deprecated and should not be used in newly-written code.

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.

`query` : | a GdaQuery object
`param_source` : | a GdaDataModel object

### gda_query_get_param_sources ()

    const GSList*       gda_query_get_param_sources         (GdaQuery *query);

### Warning

`gda_query_get_param_sources` is deprecated and should not be used in newly-written code.

Get a list of the parameter source queries that are references as such by `query`.

`query` : | a GdaQuery object
Returns : | the list of GdaQuery objects

### gda_query_add_sub_query ()

    void                gda_query_add_sub_query             (GdaQuery *query,
                                                             GdaQuery *sub_query);

### Warning

`gda_query_add_sub_query` is deprecated and should not be used in newly-written code.

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.

`query` : | a GdaQuery object
`sub_query` : | a GdaQuery object

### gda_query_del_sub_query ()

    void                gda_query_del_sub_query             (GdaQuery *query,
                                                             GdaQuery *sub_query);

### Warning

`gda_query_del_sub_query` is deprecated and should not be used in newly-written code.

Removes `sub_query` from `query`. `sub_query` MUST be present within `query`.

`query` : | a GdaQuery object
`sub_query` : | a GdaQuery object

### gda_query_get_targets ()

    GSList*             gda_query_get_targets               (GdaQuery *query);

### Warning

`gda_query_get_targets` is deprecated and should not be used in newly-written code.

Get a list of all the targets used in `query`

`query` : | a GdaQuery object
Returns : | a new list of the targets

### gda_query_add_target ()

    gboolean            gda_query_add_target                (GdaQuery *query,
                                                             GdaQueryTarget *target,
                                                             GError **error);

### Warning

`gda_query_add_target` is deprecated and should not be used in newly-written code.

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 `query`
`error` : | location to store error, or `NULL`
Returns : | TRUE if no error occurred

### gda_query_del_target ()

    void                gda_query_del_target                (GdaQuery *query,
                                                             GdaQueryTarget *target);

### Warning

`gda_query_del_target` is deprecated and should not be used in newly-written code.

Removes `target` from `query`. `target` MUST be present within `query`. Warning: All the joins and fields which depended on `target` are also removed.

`query` : | a GdaQuery object
`target` : | a GdaQueryTarget object

### gda_query_get_target_by_xml_id ()

    GdaQueryTarget*     gda_query_get_target_by_xml_id      (GdaQuery *query,
                                                             const gchar *xml_id);

### Warning

`gda_query_get_target_by_xml_id` is deprecated and should not be used in newly-written code.

Get a pointer to a GdaQueryTarget (which must be within `query`) using its XML Id

`query` : | a GdaQuery object
`xml_id` : | the XML Id of the requested GdaQueryTarget object
Returns : | the GdaQueryTarget object, or NULL if not found

### gda_query_get_target_by_alias ()

    GdaQueryTarget*     gda_query_get_target_by_alias       (GdaQuery *query,
                                                             const gchar *alias_or_name);

### Warning

`gda_query_get_target_by_alias` is deprecated and should not be used in newly-written code.

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)

`query` : | a GdaQuery object
`alias_or_name` : | the alias or name
Returns : | the GdaQueryTarget object, or NULL if not found

### gda_query_get_target_pkfields ()

    GSList*             gda_query_get_target_pkfields       (GdaQuery *query,
                                                             GdaQueryTarget *target);

### Warning

`gda_query_get_target_pkfields` is deprecated and should not be used in newly-written code.

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`.

`query` : | a GdaQuery object
`target` : | a GdaQueryTarget object
Returns : | a new GSList, or `NULL`.

### gda_query_get_joins ()

    GSList*             gda_query_get_joins                 (GdaQuery *query);

### Warning

`gda_query_get_joins` is deprecated and should not be used in newly-written code.

Get a list of all the joins used in `query`

`query` : | a GdaQuery object
Returns : | a new list of the joins

### gda_query_get_join_by_targets ()

    GdaQueryJoin*       gda_query_get_join_by_targets       (GdaQuery *query,
                                                             GdaQueryTarget *target1,
                                                             GdaQueryTarget *target2);

### Warning

`gda_query_get_join_by_targets` is deprecated and should not be used in newly-written code.

Find a join in `query` which joins the `target1` and `target2` targets

`query` : | a GdaQuery object
`target1` : | a GdaQueryTarget object
`target2` : | a GdaQueryTarget object
Returns : | the GdaQueryJoin object, or `NULL`

### gda_query_add_join ()

    gboolean            gda_query_add_join                  (GdaQuery *query,
                                                             GdaQueryJoin *join);

### Warning

`gda_query_add_join` is deprecated and should not be used in newly-written code.

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.

`query` : | a GdaQuery object
`join` : | a GdaQueryJoin object
Returns : | TRUE on success, and FALSE otherwise

### gda_query_del_join ()

    void                gda_query_del_join                  (GdaQuery *query,
                                                             GdaQueryJoin *join);

### Warning

`gda_query_del_join` is deprecated and should not be used in newly-written code.

Removes `join` from `query`. `join` MUST be present within `query`.

`query` : | a GdaQuery object
`join` : | a GdaQueryJoin object

### gda_query_get_condition ()

    GdaQueryCondition*  gda_query_get_condition             (GdaQuery *query);

### Warning

`gda_query_get_condition` is deprecated and should not be used in newly-written code.

Get the query's associated condition

`query` : | a GdaQuery object
Returns : | the GdaQueryCondition object

### gda_query_set_condition ()

    void                gda_query_set_condition             (GdaQuery *query,
                                                             GdaQueryCondition *cond);

### Warning

`gda_query_set_condition` is deprecated and should not be used in newly-written code.

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

`query` : | a GdaQuery object
`cond` : | a GdaQueryCondition object, or `NULL` to remove condition

### gda_query_add_field_from_sql ()

    GdaQueryField*      gda_query_add_field_from_sql        (GdaQuery *query,
                                                             const gchar *field,
                                                             GError **error);

### Warning

`gda_query_add_field_from_sql` is deprecated and should not be used in newly-written code.

Parses `field` and if it represents a valid SQL expression for a field, then add it to `query`.

`query` : | a GdaQuery object
`field` : | a SQL expression
`error` : | place to store the error, or `NULL`
Returns : | a new GdaQueryField object, or `NULL`

### gda_query_set_order_by_field ()

    void                gda_query_set_order_by_field        (GdaQuery *query,
                                                             GdaQueryField *field,
                                                             gint order,
                                                             gboolean ascendant);

### Warning

`gda_query_set_order_by_field` is deprecated and should not be used in newly-written code.

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 `query`
`order` : | the order in the list of ORDER BY fields (starts at 0), or -1
`ascendant` : | TRUE to sort ascending

### gda_query_get_order_by_field ()

    gint                gda_query_get_order_by_field        (GdaQuery *query,
                                                             GdaQueryField *field,
                                                             gboolean *ascendant);

### Warning

`gda_query_get_order_by_field` is deprecated and should not be used in newly-written code.

Tells if `field` (which MUST be in `query`) is part of the ORDER BY clause.

`query` : | a GdaQuery
`field` : | a GdaQueryField which is in `query`
`ascendant` : | if not `NULL`, will be set TRUE if ascendant sorting and FALSE otherwise
Returns : | -1 if no, and the order where it appears in the ORDER BY list otherwise

### gda_query_set_results_limit ()

    void                gda_query_set_results_limit         (GdaQuery *query,
                                                             gboolean has_limit,
                                                             guint limit,
                                                             guint offset);

### Warning

`gda_query_set_results_limit` is deprecated and should not be used in newly-written code.

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` and `offset` are ignored)
`limit` : | the maximum number of rows returned
`offset` : | the row offset to start getting rows

### gda_query_get_results_limit ()

    gboolean            gda_query_get_results_limit         (GdaQuery *query,
                                                             guint *limit,
                                                             guint *offset);

### Warning

`gda_query_get_results_limit` is deprecated and should not be used in newly-written code.

For a SELECT query, get the limits for the number of rows returned when the query is executed

`query` : | a GdaQuery object
`limit` : | a place to store the maximum number of rows returned, or `NULL`
`offset` : | a place to store the row offset to start getting rows, or `NULL`
Returns : | FALSE if no limit is set in `query` (in which case `limit` and `offset` are unchanged)

### gda_query_get_all_fields ()

    GSList*             gda_query_get_all_fields            (GdaQuery *query);

### Warning

`gda_query_get_all_fields` is deprecated and should not be used in newly-written code.

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.

`query` : | a GdaQuery object
Returns : | a new list of fields

### gda_query_get_field_by_sql_naming ()

    GdaQueryField*      gda_query_get_field_by_sql_naming   (GdaQuery *query,
                                                             const gchar *sql_name);

### Warning

`gda_query_get_field_by_sql_naming` is deprecated and should not be used in newly-written code.

`query` : | a GdaQuery object
`sql_name` : | the SQL naming for the requested field
Returns : |

### gda_query_get_field_by_sql_naming_fields ()

    GdaQueryField*      gda_query_get_field_by_sql_naming_fields
                                                            (GdaQuery *query,
                                                             const gchar *sql_name,
                                                             GSList *fields_list);

### Warning

`gda_query_get_field_by_sql_naming_fields` is deprecated and should not be used in newly-written code.

`query` : | a GdaQuery object
`sql_name` : | the SQL naming for the requested field
`fields_list` : | an explicit list of fields to search into
Returns : |

### gda_query_get_fields_by_target ()

    GSList*             gda_query_get_fields_by_target      (GdaQuery *query,
                                                             GdaQueryTarget *target,
                                                             gboolean visible_fields_only);

### Warning

`gda_query_get_fields_by_target` is deprecated and should not be used in newly-written code.

Get a list of all the GdaQueryField objects in `query` which depent on the existance of `target`.

`query` : | a GdaQuery object
`target` : | a GdaQueryTarget object representing a target in `query`
`visible_fields_only` : |
Returns : | a new list of GdaQueryField objects

### gda_query_get_main_conditions ()

    GSList*             gda_query_get_main_conditions       (GdaQuery *query);

### Warning

`gda_query_get_main_conditions` is deprecated and should not be used in newly-written code.

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}

`query` : | a GdaQuery object
Returns : | a new list of GdaQueryCondition objects

### gda_query_append_condition ()

    void                gda_query_append_condition          (GdaQuery *query,
                                                             GdaQueryCondition *cond,
                                                             gboolean append_as_and);

### Warning

`gda_query_append_condition` is deprecated and should not be used in newly-written code.

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

### gda_query_expand_all_field ()

    GSList*             gda_query_expand_all_field          (GdaQuery *query,
                                                             GdaQueryTarget *target);

### Warning

`gda_query_expand_all_field` is deprecated and should not be used in newly-written code.

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()`.

`query` : | a GdaQuery object
`target` : | a GdaQueryTarget, or `NULL`
Returns : | a new list of the GdaQueryField objects which have been created

### gda_query_order_fields_using_join_conds ()

    void                gda_query_order_fields_using_join_conds
                                                            (GdaQuery *query);

### Warning

`gda_query_order_fields_using_join_conds` is deprecated and should not be used in newly-written code.

Re-orders the fields in `query` using the joins' conditions: for each join condition, the used query fields are grouped together near the 1st visible field.

`query` : | a GdaQuery object

## Property Details

### The `"auto-clean"` property

      "auto-clean"               gboolean              : Read / Write

Determines if the query tries to clean unused objects.

Default value: TRUE

### The `"cond-serial"` property

      "cond-serial"              guint                 : Read

Allowed values: >= 1

Default value: 1

### The `"field-serial"` property

      "field-serial"             guint                 : Read

Allowed values: >= 1

Default value: 1

### The `"really-all-fields"` property

      "really-all-fields"        gpointer              : Read

### The `"target-serial"` property

      "target-serial"            guint                 : Read

Allowed values: >= 1

Default value: 1

## Signal Details

### The `"condition-changed"` signal

    void                user_function                      (GdaQuery *gdaquery,
                                                            gpointer  user_data)      : Run First

`dbquery` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"join-added"` signal

    void                user_function                      (GdaQuery     *gdaquery,
                                                            GdaQueryJoin *arg1,
                                                            gpointer      user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"join-removed"` signal

    void                user_function                      (GdaQuery     *gdaquery,
                                                            GdaQueryJoin *arg1,
                                                            gpointer      user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"join-updated"` signal

    void                user_function                      (GdaQuery     *gdaquery,
                                                            GdaQueryJoin *arg1,
                                                            gpointer      user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"sub-query-added"` signal

    void                user_function                      (GdaQuery *gdaquery,
                                                            GdaQuery *arg1,
                                                            gpointer  user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"sub-query-removed"` signal

    void                user_function                      (GdaQuery *gdaquery,
                                                            GdaQuery *arg1,
                                                            gpointer  user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"sub-query-updated"` signal

    void                user_function                      (GdaQuery *gdaquery,
                                                            GdaQuery *arg1,
                                                            gpointer  user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"target-added"` signal

    void                user_function                      (GdaQuery       *gdaquery,
                                                            GdaQueryTarget *arg1,
                                                            gpointer        user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"target-removed"` signal

    void                user_function                      (GdaQuery       *gdaquery,
                                                            GdaQueryTarget *arg1,
                                                            gpointer        user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"target-updated"` signal

    void                user_function                      (GdaQuery       *gdaquery,
                                                            GdaQueryTarget *arg1,
                                                            gpointer        user_data)      : Run First

`dbquery` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"type-changed"` signal

    void                user_function                      (GdaQuery *gdaquery,
                                                            gpointer  user_data)      : Run First

`dbquery` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.