GdaDataSelect

## GdaDataSelect GdaDataSelect — Data models returned by the execution of a SELECT statement |

## Synopsis

    struct              GdaDataSelect;
    enum                GdaDataSelectError;
    gboolean            gda_data_select_set_row_selection_condition_sql
                                                            (GdaDataSelect *model,
                                                             const gchar *sql_where,
                                                             GError **error);
    gboolean            gda_data_select_set_row_selection_condition
                                                            (GdaDataSelect *model,
                                                             GdaSqlExpr *expr,
                                                             GError **error);
    gboolean            gda_data_select_compute_row_selection_condition
                                                            (GdaDataSelect *model,
                                                             GError **error);
    gboolean            gda_data_select_set_modification_statement
                                                            (GdaDataSelect *model,
                                                             GdaStatement *mod_stmt,
                                                             GError **error);
    gboolean            gda_data_select_set_modification_statement_sql
                                                            (GdaDataSelect *model,
                                                             const gchar *sql,
                                                             GError **error);
    gboolean            gda_data_select_compute_modification_statements
                                                            (GdaDataSelect *model,
                                                             GError **error);
    enum                GdaDataSelectConditionType;
    gboolean            gda_data_select_compute_modification_statements_ext
                                                            (GdaDataSelect *model,
                                                             GdaDataSelectConditionType cond_type,
                                                             GError **error);
    gboolean            gda_data_select_compute_columns_attributes
                                                            (GdaDataSelect *model,
                                                             GError **error);
    gboolean            gda_data_select_rerun               (GdaDataSelect *model,
                                                             GError **error);
    void                gda_data_select_add_exception       (GdaDataSelect *model,
                                                             GError *error);

## Object Hierarchy

      GObject
       +----GdaDataSelect

## Implemented Interfaces

GdaDataSelect implements GdaDataModel.

## Properties

      "auto-reset"               gboolean              : Read / Write
      "connection"               GdaConnection*        : Read / Write / Construct Only
      "delete-stmt"              GdaStatement*         : Read / Write
      "exec-params"              GdaSet*               : Read / Write / Construct Only
      "execution-delay"          gdouble               : Read / Write
      "insert-stmt"              GdaStatement*         : Read / Write
      "model-usage"              guint                 : Read / Write / Construct Only
      "prepared-stmt"            GdaPStmt*             : Read / Write
      "select-stmt"              GdaStatement*         : Read
      "store-all-rows"           gboolean              : Read / Write
      "update-stmt"              GdaStatement*         : Read / Write

## Description

This data model implements the GdaDataModel interface and is the required base object when database providers implement a data model returned when a SELECT statement has been executed. As the GdaDataModel interface is implemented, consult the API to access and modify the data held in a GdaDataSelect object.

The default behaviour however is to disallow modifications, and this section documents how to characterize a GdaDataSelect to allow modifications. Once this is done, any modification done to the data model will be propagated to the modified table in the database using INSERT, UPDATE or DELETE statements.

After any modification, it is still possible to read values from the data model (even values for rows which have been modified or inserted). The data model might then execute some SELECT statement to fetch some actualized values. Note: there is a corner case where a modification made to a row would make the row not selected at first in the data model (for example is the original SELECT statement included a clause "WHERE id < 100" and the modification sets the "id" value to 110), then the row will still be in the data model even though it would not be if the SELECT statement which execution created the data model in the first place was re-run. This is illustrated in the schema below:

## Details

### struct GdaDataSelect

    struct GdaDataSelect;

### enum GdaDataSelectError

    typedef enum {
    	GDA_DATA_SELECT_MODIFICATION_STATEMENT_ERROR,
    	GDA_DATA_SELECT_MISSING_MODIFICATION_STATEMENT_ERROR,
    	GDA_DATA_SELECT_CONNECTION_ERROR,
    	GDA_DATA_SELECT_ACCESS_ERROR,
    	GDA_DATA_SELECT_SQL_ERROR,
    	GDA_DATA_SELECT_SAFETY_LOCKED_ERROR
    } GdaDataSelectError;

### gda_data_select_set_row_selection_condition_sql ()

    gboolean            gda_data_select_set_row_selection_condition_sql
                                                            (GdaDataSelect *model,
                                                             const gchar *sql_where,
                                                             GError **error);

Specifies the SQL condition corresponding to the WHERE part of a SELECT statement which would return only 1 row (the expression of the primary key).

For example for a table created as "CREATE TABLE mytable (part1 int NOT NULL, part2 string NOT NULL, name string, PRIMARY KEY (part1, part2))", and if `pmodel` corresponds to the execution of the "SELECT name, part1, part2 FROM mytable", then the sensible value for `sql_where` would be "part1 = ##-1::int AND part2 = ##-2::string" because the values of the 'part1' field are located in `pmodel`'s column number 1 and the values of the 'part2' field are located in `pmodel`'s column number 2 and the primary key is composed of (part1, part2).

For more information about the syntax of the parameters (named "##-1::int" for example), see the GdaSqlParser documentation, and `gda_data_select_set_modification_statement()`.

`model` : | a GdaDataSelect data model
`sql_where` : | an SQL condition (without the WHERE keyword)
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_data_select_set_row_selection_condition ()

    gboolean            gda_data_select_set_row_selection_condition
                                                            (GdaDataSelect *model,
                                                             GdaSqlExpr *expr,
                                                             GError **error);

Offers the same features as `gda_data_select_set_row_selection_condition_sql()` but using a GdaSqlExpr structure instead of an SQL syntax.

`model` : | a GdaDataSelect data model
`expr` : | a GdaSqlExpr expression. [transfer none]
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_data_select_compute_row_selection_condition ()

    gboolean            gda_data_select_compute_row_selection_condition
                                                            (GdaDataSelect *model,
                                                             GError **error);

Offers the same features as `gda_data_select_set_row_selection_condition()` but the expression is computed from the meta data associated to the connection being used when `model` was created.

NOTE1: make sure the meta data associated to the connection is up to date before using this method, see `gda_connection_update_meta_store()`.

NOTE2: if the SELECT statement from which `model` has been created uses more than one table, or if the table used does not have any primary key, then this method will fail

`model` : | a GdaDataSelect object
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred.

### gda_data_select_set_modification_statement ()

    gboolean            gda_data_select_set_modification_statement
                                                            (GdaDataSelect *model,
                                                             GdaStatement *mod_stmt,
                                                             GError **error);

Informs `model` that it should allow modifications to the data in some columns and some rows using `mod_stmt` to propagate those modifications into the database.

If `mod_stmt` is:

- an UPDATE statement, then all the rows in `model` will be modifyable

- a DELETE statement, then it will be possible to delete rows in `model`

- in INSERT statement, then it will be possible to add some rows to `model`

- any other statement, then this method will return an error

This method can be called several times to specify different types of modification.

If `mod_stmt` is an UPDATE or DELETE statement then it should have a WHERE part which identifies a unique row in `model` (please note that this property can't be checked but may result in `model` behaving in an unpredictable way).

NOTE1: However, if the `gda_data_select_set_row_selection_condition()` or `gda_data_select_set_row_selection_condition_sql()` have been successfully be called before, the WHERE part of `mod_stmt` WILL be modified to use the row selection condition specified through one of these methods (please not that it is then possible to avoid specifying a WHERE part in `mod_stmt` then).

NOTE2: if `gda_data_select_set_row_selection_condition()` or `gda_data_select_set_row_selection_condition_sql()` have not yet been successfully be called before, then the WHERE part of `mod_stmt` will be used as if one of these functions had been called.

`model` : | a GdaDataSelect data model
`mod_stmt` : | a GdaStatement (INSERT, UPDATE or DELETE)
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred.

### gda_data_select_set_modification_statement_sql ()

    gboolean            gda_data_select_set_modification_statement_sql
                                                            (GdaDataSelect *model,
                                                             const gchar *sql,
                                                             GError **error);

Offers the same feature as `gda_data_select_set_modification_statement()` but using an SQL statement

`model` : | a GdaDataSelect data model
`sql` : | an SQL text
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred.

### gda_data_select_compute_modification_statements ()

    gboolean            gda_data_select_compute_modification_statements
                                                            (GdaDataSelect *model,
                                                             GError **error);

Makes `model` try to compute INSERT, UPDATE and DELETE statements to be used when modifying `model`'s contents. Note: any modification statement set using `gda_data_select_set_modification_statement()` will first be unset

This function is similar to calling gda_data_select_compute_modification_statements_ext with `cond_type` set to `GDA_DATA_SELECT_COND_PK`

`model` : | a GdaDataSelect data model
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if no error occurred. If `FALSE` is returned, then some modification statement may still have been computed

### enum GdaDataSelectConditionType

    typedef enum {
    	GDA_DATA_SELECT_COND_PK,
    	GDA_DATA_SELECT_COND_ALL_COLUMNS
    } GdaDataSelectConditionType;

Defines what criteria `gda_data_select_compute_modification_statements_ext()` uses to uniquely identify a single row in a table when creating modification statements.

`GDA_DATA_SELECT_COND_PK` | only primary key fields are used
`GDA_DATA_SELECT_COND_ALL_COLUMNS` | all the columns of the tables are used

### gda_data_select_compute_modification_statements_ext ()

    gboolean            gda_data_select_compute_modification_statements_ext
                                                            (GdaDataSelect *model,
                                                             GdaDataSelectConditionType cond_type,
                                                             GError **error);

Makes `model` try to compute INSERT, UPDATE and DELETE statements to be used when modifying `model`'s contents. Note: any modification statement set using `gda_data_select_set_modification_statement()` will first be unset

`model` : | a GdaDataSelect data model
`cond_type` : | the type of condition for the modifications where one row only should be identified
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if no error occurred. If `FALSE` is returned, then some modification statement may still have been computed

Since 4.2.9

### gda_data_select_compute_columns_attributes ()

    gboolean            gda_data_select_compute_columns_attributes
                                                            (GdaDataSelect *model,
                                                             GError **error);

Computes correct attributes for each of `model`'s columns, which includes the "NOT NULL" attribute, the default value, the precision and scale for numeric values.

`model` : | a GdaDataSelect data model
`error` : | a place to store errors, or `NULL`
Returns : | TRUE if no error occurred

### gda_data_select_rerun ()

    gboolean            gda_data_select_rerun               (GdaDataSelect *model,
                                                             GError **error);

Requests that `model` be re-run to have an updated result. If an error occurs, then `model` will not be changed.

`model` : | a GdaDataSelect data model
`error` : | a place to store errors, or `NULL`
Returns : | `TRUE` if no error occurred

Since 4.2

### gda_data_select_add_exception ()

    void                gda_data_select_add_exception       (GdaDataSelect *model,
                                                             GError *error);

Add an exception to `model`.

`model` : | a GdaDataSelect
`error` : | an error to add as exception. [transfer full]

Since 4.2.6

## Property Details

### The `"auto-reset"` property

      "auto-reset"               gboolean              : Read / Write

Automatically re-run the SELECT statement if any parameter has changed since it was first executed.

Default value: FALSE

### The `"connection"` property

      "connection"               GdaConnection*        : Read / Write / Construct Only

Connection from which this data model is created.

### The `"delete-stmt"` property

      "delete-stmt"              GdaStatement*         : Read / Write

DELETE Statement to be executed to remove data.

### The `"exec-params"` property

      "exec-params"              GdaSet*               : Read / Write / Construct Only

GdaSet used when the SELECT statement was executed.

### The `"execution-delay"` property

      "execution-delay"          gdouble               : Read / Write

This property stores the execution delay which has been necessary to obtain the data

Allowed values: >= 0

Default value: 0

Since 4.2.9

### The `"insert-stmt"` property

      "insert-stmt"              GdaStatement*         : Read / Write

INSERT Statement to be executed to add data.

### The `"model-usage"` property

      "model-usage"              guint                 : Read / Write / Construct Only

Determines how the data model may be used.

Allowed values: >= 1

Default value: 1

### The `"prepared-stmt"` property

      "prepared-stmt"            GdaPStmt*             : Read / Write

Associated prepared statement (for internal usage).

### The `"select-stmt"` property

      "select-stmt"              GdaStatement*         : Read

SELECT statement which was executed to yield to the data model.

### The `"store-all-rows"` property

      "store-all-rows"           gboolean              : Read / Write

Tells if model has analyzed all the rows.

Default value: FALSE

### The `"update-stmt"` property

      "update-stmt"              GdaStatement*         : Read / Write

UPDATE Statement to be executed to update data.

## See Also

The Advanced GdaDataSelect usage section.