GdaDataSelect

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

Stability Level

Stable, unless otherwise indicated

Properties

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

Types and Values

Object Hierarchy

    GObject
    ╰── GdaDataSelect

Implemented Interfaces

GdaDataSelect implements GdaDataModel.

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:

GdaDataSelect data model's contents after some modifications

Functions

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

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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


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

Parameters

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.

Parameters

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.

Parameters

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 .

Parameters

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

Parameters

model

a GdaDataSelect object

 

error

a place to store errors, or NULL.

[allow-none]

Returns

TRUE if no error occurred

Since 5.2.0

Types and Values

struct GdaDataSelect

struct GdaDataSelect;

enum GdaDataSelectError

Members

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

   

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

Members

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

 

Property Details

The “auto-reset” property

  “auto-reset”               gboolean

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

Flags: Read / Write

Default value: FALSE


The “connection” property

  “connection”               GdaConnection *

Connection from which this data model is created.

Flags: Read / Write / Construct Only


The “delete-stmt” property

  “delete-stmt”              GdaStatement *

DELETE Statement to be executed to remove data.

Flags: Read / Write


The “exec-params” property

  “exec-params”              GdaSet *

GdaSet used when the SELECT statement was executed.

Flags: Read / Write / Construct Only


The “execution-delay” property

  “execution-delay”          gdouble

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

Flags: Read / Write

Allowed values: >= 0

Default value: 0

Since 4.2.9


The “insert-stmt” property

  “insert-stmt”              GdaStatement *

INSERT Statement to be executed to add data.

Flags: Read / Write


The “model-usage” property

  “model-usage”              guint

Determines how the data model may be used.

Flags: Read / Write / Construct Only

Allowed values: >= 1

Default value: 1


The “prepared-stmt” property

  “prepared-stmt”            GdaPStmt *

Associated prepared statement (for internal usage).

Flags: Read / Write


The “select-stmt” property

  “select-stmt”              GdaStatement *

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

Flags: Read


The “store-all-rows” property

  “store-all-rows”           gboolean

Tells if model has analyzed all the rows.

Flags: Read / Write

Default value: FALSE


The “update-stmt” property

  “update-stmt”              GdaStatement *

UPDATE Statement to be executed to update data.

Flags: Read / Write

See Also

GdaDataModel and the Advanced GdaDataSelect usage section.