GdaDataSelect

## GdaDataSelect GdaDataSelect — Base class for data models returned by the execution of a SELECT statement |

## Stability Level

Stable, unless otherwise indicated

## 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);
    gboolean            gda_data_select_prepare_for_offline (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.

Depending on the requested data model usage (as specified by the "model_usage" parameter of the `gda_connection_statement_execute()` and similar methods, the GdaDataSelect will allow random access, cursor based access or both.

Also, when later you'll be reading the data contained in a GdaDataSelect object, depending on the actual implementation (which adapts to the API providede by the database server), some calls to the database server may be necessary to actually obtain the data. If this behaviour is not the one intended and if you need to access the data without having to contact the database server (for example for performances reasons), then you can use the `gda_data_select_prepare_for_offline()` method or specify the GDA_STATEMENT_MODEL_OFFLINE flag when executing the SELECT statement.

The default behaviour however is to disallow modifications, and this section documents how to parametrize 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`. [allow-none]
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`. [allow-none]
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`. [allow-none]
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 writable

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

Each modification statement will be executed when one or more values are modified in the data model; each statement should then include variables which will be set to either the old value or the new value of a column at the specified modified row (but can also contain other variables). Each variable named as "+<number>" will be mapped to the new value of the number'th column (starting at 0), and each variable named as "-<number>" will be mapped to the old value of the number'th column.

Examples of the SQL equivalent of each statement are (for example if "mytable" has the "id" field as primary key, and if that field is auto incremented and if the data model is the result of executing "SELECT * from mytable").

- "INSERT INTO mytable (name) VALUES (##+1::string)": the column ID can not be set for new rows

- "DELETE FROM mytable WHERE id=##-0::int"

- "UPDATE mytable SET name=##+1::string WHERE id=##-0::int": the column ID cannot be modified

Also see the `gda_data_select_set_row_selection_condition_sql()` for more information about the WHERE part of the UPDATE and DELETE statement types.

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`. [allow-none]
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`. [allow-none]
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`. [allow-none]
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`. [allow-none]
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`. [allow-none]
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`. [allow-none]
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

### gda_data_select_prepare_for_offline ()

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

Use this method to make sure all the data contained in the data model are stored on the client side (and that no subsquent call to the server will be necessary to access that data), at the cost of a higher memory consumption.

This method is useful in the following situations:

- You need to disconnect from the server and continue to use the data in the data model

- You need to make sure the data in the data model can be used even though the connection to the server may be used for other purposes (for example executing other queries)

Note that this method will fail if:

- the data model contains any blobs (because blobs reading requires acces to the server); binary values are Ok, though.

- the data model has been modified since it was created

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

Since 5.2.0

## 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

GdaDataModel and the Advanced GdaDataSelect usage section.