struct MidgardQueryBuilder

struct MidgardQueryBuilder;

MidgardQueryBuilderPrivate

typedef struct {
	GSList *constraints;
	GSList *groups;
	gboolean is_grouping;
	guint grouping_ref;
	MidgardGroupConstraint *group_constraint;
	GSList *joins;
	GHashTable *tables;
	GSList *orders;
	GValue *value;

	/* constants */
	MidgardConnection *mgd;
	MgdSchemaTypeAttr *schema;
	GType type;

	guint offset;
	guint limit;
	gboolean include_deleted;
	gboolean select_distinct;
	gint error;

	/* references for reserved joins */
	gboolean param_join_exists;
	gboolean blob_join_exists;
} MidgardQueryBuilderPrivate;

MidgardQueryBuilderClass

typedef struct MidgardQueryBuilderClass MidgardQueryBuilderClass;

midgard_query_builder_new ()

MidgardQueryBuilder * midgard_query_builder_new         (MidgardConnection *mgd,
                                                         const gchar *classname);

midgard_query_builder_create_builder ()

MidgardQueryBuilder * midgard_query_builder_create_builder
                                                        (MidgardConnection *mgd,
                                                         const gchar *classname);

Static constructor. Invokes midgard_query_builder_new(). This function is added for language bindings, in which, that function can not be invoked explicitly.

Since 10.05.1

midgard_query_builder_add_constraint ()

gboolean            midgard_query_builder_add_constraint
                                                        (MidgardQueryBuilder *builder,
                                                         const gchar *name,
                                                         const gchar *op,
                                                         const GValue *value);

Adds a constraint to the given query builder. The constraint is expressed as a triple of a field name, a comparison operator, and a comparison value.

name referes to a property of the queried Midgard object class. For example, MidgardQueryBuilder has been initialized for person class which has lastname property registered.

GValue value = {0, };
g_value_init(&value, G_TYPE_STRING);
g_value_set_string(&value, "smith");

midgard_query_builder_add_constraint(builder, "lastname", "=", &value);

It also can be name of the linked class property or reserved one. A dot '.' is used to separate properties for special constraints. If such special constraint property is used, MidgardQueryBuilder performs right join.

The comparison operator is a string representation of the requested comparison. Available operators are =, <>, <, >, <=, >=, LIKE, NOT LIKE, IN, INTREE.

The given value is copied and converted into the property type before comparison.

midgard_query_builder_add_constraint_with_property ()

gboolean            midgard_query_builder_add_constraint_with_property
                                                        (MidgardQueryBuilder *builder,
                                                         const gchar *property_a,
                                                         const gchar *op,
                                                         const gchar *property_b);

Adds named property constraint to the given query builder. Unlike add_constraint method, this one accepts property name instead of scalar value. The difference is that with add_constraint method you can compare property with particular value, while using add_constraint_with_property method you can compare two different properties without any need to know their values. For example, you should use this method if you want to select only those objects which has been revised after publication time, and particular date doesn't matter.

midgard_query_builder_add_constraint_with_property(builder, "metadata.revised", ">", "metadata.published");

See: midgard_query_builder_add_constraint()

midgard_query_builder_begin_group ()

gboolean            midgard_query_builder_begin_group   (MidgardQueryBuilder *builder,
                                                         const gchar *type);

Starts a constraint group of the given type. A conjunctive constraint group type (AND) requires that all component constraints match the queried objects, while a disjunctive group type (OR) requires just one of the component constraints to match.

Allowed group type: 'AND' or 'OR'

midgard_query_builder_end_group ()

gboolean            midgard_query_builder_end_group     (MidgardQueryBuilder *builder);

Closes the most recently opened constraint group. The client should ensure proper nesting by closing all constraint groups before the containing query is executed.

midgard_query_builder_add_order ()

gboolean            midgard_query_builder_add_order     (MidgardQueryBuilder *builder,
                                                         const gchar *name,
                                                         const gchar *dir);

Adds an ordering constraint to the query. An ordering constraint consists of a property name and a sort direction. The objects returned by this query will be sorted by the given property in the given direction (ascending or descending). Multiple ordering constraints are applied in the order they were added.

Allowed sort directions: 'ASC' or 'DESC'

Property name pattern is described in midgard_query_builder_add_constraint()

midgard_query_builder_set_offset ()

void                midgard_query_builder_set_offset    (MidgardQueryBuilder *builder,
                                                         guint offset);

Sets the start offset of the objects to return when the query is executed. The start offset is applied after all the matching objects have been identified and sorted according to the given ordering constraints. The first offset objects are skipped and only the remaining (if any) objects are returned to the client.

Setting a start offset is normally only reasonable when one or more ordering constraints are applied to the query. A start offset is usually accompanied by a limit setting.

See: midgard_query_builder_set_offset()

midgard_query_builder_set_limit ()

void                midgard_query_builder_set_limit     (MidgardQueryBuilder *builder,
                                                         guint limit);

Sets the maximum number of objects to return when the query is executed. A query will by default return all matching objects, but the limit setting can be used to restrict the potentially large number of returned objects. The limit is applied only after the matching objects have been identified and sorted and after the optional start offset has been applied.

Setting a limit on the number of returned objects is normally only reasonable when one or more ordering constraints and optionally an offset setting are applied to the query.

See: midgard_query_builder_set_offset()

midgard_query_builder_execute ()

GObject **          midgard_query_builder_execute       (MidgardQueryBuilder *builder,
                                                         guint *n_objects);

Executes the built query.

Objects in returned array are MidgardDBObject derived ones, and typecasted to base GObject. You can safely typecast them to the type, which MidgardQueryBuilder has been initialized for.

In case of any error, MidgardConnection error is set.

midgard_query_builder_count ()

guint               midgard_query_builder_count         (MidgardQueryBuilder *builder);

Returns the number of objects that this query would return when executed without limit or start offset settings.

midgard_query_builder_get_type_name ()

const gchar *       midgard_query_builder_get_type_name (MidgardQueryBuilder *builder);

Returns type name of the type which is currently used by Query Builder.

This function should be used on language binding level , when internal Query Builder's instance is already created and language binding object should be instanciated.

Returned type name is a pointer and is owned by GLib system. Caller shouldn't free it.

midgard_query_builder_include_deleted ()

void                midgard_query_builder_include_deleted
                                                        (MidgardQueryBuilder *builder);

Query all objects - deleted and undeleted.

This is valid for a class for which metadata is defined ('deleted' property of MidgardMetadata class), or class has 'metadata' property installed. If none of them is found, this method does nothing.

The "execution-end" signal

void                user_function                      (MidgardQueryBuilder *midgardquerybuilder,
                                                        gpointer             user_data)                : No Hooks

The "execution-start" signal

void                user_function                      (MidgardQueryBuilder *midgardquerybuilder,
                                                        gpointer             user_data)                : No Hooks