Midgard Query Builder

Data Structures
struct	MidgardQueryBuilderClass
Typedefs
typedef MidgardQueryBuilder	MidgardQueryBuilder
typedef MidgardQueryBuilderClass	MidgardQueryBuilderClass
Functions
GType	midgard_query_builder_get_type (void)
MidgardQueryBuilder *	midgard_query_builder_new (midgard *mgd, const gchar *classname)
void	midgard_query_builder_free (MidgardQueryBuilder *builder)
void	midgard_query_builder_set_lang (MidgardQueryBuilder *builder, gint lang)
void	midgard_query_builder_unset_languages (MidgardQueryBuilder *builder)
gboolean	midgard_query_builder_add_constraint (MidgardQueryBuilder *builder, const gchar *name, const gchar *op, const GValue *value)
gboolean	midgard_query_builder_begin_group (MidgardQueryBuilder *builder, const gchar *type)
gboolean	midgard_query_builder_end_group (MidgardQueryBuilder *builder)
gboolean	midgard_query_builder_add_order (MidgardQueryBuilder *builder, const gchar *name, const gchar *dir)
void	midgard_query_builder_set_offset (MidgardQueryBuilder *builder, guint offset)
void	midgard_query_builder_set_limit (MidgardQueryBuilder *builder, guint limit)
GObject **	midgard_query_builder_execute (MidgardQueryBuilder *builder, guint *n_objects)
guint	midgard_query_builder_count (MidgardQueryBuilder *builder)
gboolean	midgard_query_builder_join (MidgardQueryBuilder *builder, const gchar *prop, const gchar *jobject, const gchar *jprop)
GList *	midgard_query_builder_get_guid (MidgardQueryBuilder *builder)
const gchar *	midgard_query_builder_get_type_name (MidgardQueryBuilder *builder)
void	midgard_query_builder_include_deleted (MidgardQueryBuilder *builder)

---

Detailed Description

The Midgard Query Builder allows an application to construct and execute queries against the Midgard database. The main steps of using the query builder are:

• create a query builder instance
• add constraints and other options to the query
• execute the query

Each query is represented by an instance of the opaque MidgardQueryBuilder structure. The midgard_query_builder functions can be used to manipulate the queries.

---

Typedef Documentation

typedef struct MidgardQueryBuilder MidgardQueryBuilder

The opaque Midgard Query Builder type. Instances are used to track the state of a query builder. Definition at line 58 of file query_builder.h.

typedef struct MidgardQueryBuilderClass MidgardQueryBuilderClass

The opaque Midgard Query Builder class. Definition at line 87 of file query_builder.h.

---

Function Documentation

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 scalar comparison value. The field name referes to a property of the queried Midgard object class. The comparison operator is a string representation of the requested comparison. Available operators are =, <>, <, >, <=, >=, and LIKE. The given scalar value is copied and converted into the property type before comparison. This method returns TRUE if the given constraint is valid (refers to a valid field, uses a valid operator, and contains a valid value). Otherwise this method returns FALSE and does not change the state of the query builder. Parameters: builder  query builder [in]  name  name of the field used for the constraint [in]  op  comparison operator [in]  value  scalar value used in comparison Returns: TRUE if the constraint is valid, FALSE otherwise Definition at line 383 of file query_builder.c. References MidgardQueryBuilder::error, MidgardSimpleConstraint::ext_type, MidgardQueryBuilder::ext_type, MidgardSimpleConstraint::initial_klass, MidgardQueryBuilder::mgd, MidgardSimpleConstraint::parent_type, MidgardQueryBuilder::parent_type, MidgardQueryBuilder::stack, MidgardQueryBuilder::type, MidgardSimpleConstraint::types, and MidgardQueryBuilder::types. Referenced by midgard_collector_new(), midgard_collector_set_key_property(), midgard_import_object(), midgard_object_find(), midgard_object_get_by_guid(), midgard_object_get_by_id(), midgard_object_list(), midgard_object_list_children(), midgard_object_new(), and midgard_object_set_parameter().

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. Parameters: builder  query builder [in]  name  name of the order property [in]  dir  sort direction (ASC or DESC) Returns: TRUE if the ordering constraint is valid, FALSE otherwise Definition at line 456 of file query_builder.c. References MidgardQueryOrder::ext_type, MidgardQueryBuilder::ext_type, MidgardQueryBuilder::mgd, MidgardQueryBuilder::orders, MidgardQueryOrder::parent_type, MidgardQueryBuilder::parent_type, and MidgardQueryBuilder::type.

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. Parameters: builder  query builder [in]  type  group type (AND or OR) Returns: TRUE if the type is valid (AND or OR), FALSE otherwise Definition at line 427 of file query_builder.c. References MidgardQueryBuilder::stack.

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. Warning: At the moment this function is implemented by simply calling midgard_query_builder_execute and discarding all the returned objects. An optimized version of this function is however being planned, so applications should feel free to start using this function. Returns: number of objects matched by this query Definition at line 598 of file query_builder.c. References MidgardQueryBuilder::mgd, MGD_ERR_OK, and MIDGARD_ERRNO_SET.

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. Parameters: builder  query builder Returns: TRUE if a constraint group was closed, or FALSE if no open constraint groups were found Definition at line 444 of file query_builder.c. References MidgardQueryBuilder::stack.

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

Executes the built query. The matched recors are returned as full MgdObjects. Parameters: builder  query builder [out]  n_objects  place to store the number of returned objects Returns: objects matched by the query Definition at line 578 of file query_builder.c. References _MgdObject::data, MidgardQueryBuilder::mgd, MGD_ERR_OK, and MIDGARD_ERRNO_SET. Referenced by midgard_import_object(), midgard_object_get_by_guid(), midgard_object_get_by_id(), midgard_object_list(), midgard_object_list_children(), midgard_object_new(), and midgard_object_set_parameter().

void midgard_query_builder_free (  MidgardQueryBuilder *  builder  )

Releases the given query builder and all associated resources. Parameters: builder  query builder Definition at line 357 of file query_builder.c. References MidgardQueryBuilder::orders, and MidgardQueryBuilder::stack.

GList* midgard_query_builder_get_guid (  MidgardQueryBuilder *  builder  )

Executes the built query. The matched recors are returned as object's guid. Look at midgard_query_builder_execute which returns full objects. Parameters: builder  Midgard Query Builder object's instance Returns: Glist Data member of returned list contains object's guid. Caller is responsible to free memory allocated by all list's data and list itself. Definition at line 616 of file query_builder.c.

GType midgard_query_builder_get_type (  void   )

Returns MidgardQueryBuilder type. Registers the type as a fundamental GType unless already registered. Definition at line 968 of file query_builder.c.

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. Parameters: builder  Midgard Query Builder object's instance Returns: type name Returned type name is a pointer and is owned by GLib system. Caller shouldn't free it. Definition at line 921 of file query_builder.c. References MidgardQueryBuilder::type.

void midgard_query_builder_include_deleted (  MidgardQueryBuilder *  builder  )

Include deleted objects. Parameters: builder,MidgardQueryBuilder  instance pointer Normally Query Builder queries only undeleted objects. This method forces QB instance to query both, deleted and undeleted objects. Definition at line 928 of file query_builder.c. References MidgardQueryBuilder::include_deleted. Referenced by midgard_import_object().

gboolean midgard_query_builder_join (  MidgardQueryBuilder *  builder, const gchar *  prop, const gchar *  jobject, const gchar *  jprop )

Joins type's properties' fields in query. Parameters: builder  Midgard Query Builder object's instance prop  property which is a memeber of builder type jobject  typename which property should be joined jprop  property which should be joined Returns: TRUE if properties are valid for defined types and query can be built , FALSE otherwise Definition at line 849 of file query_builder.c. References MidgardQueryBuilder::join, MidgardQueryBuilder::link, MidgardQueryBuilder::mgd, midgard_object_new(), MidgardQueryBuilder::tables, and MidgardQueryBuilder::type. Here is the call graph for this function:

MidgardQueryBuilder* midgard_query_builder_new (  midgard *  mgd, const gchar *  classname )

Creates a new query builder for the given Midgard connection and MgdSchema class. Returns NULL if the named MgdSchema class is not found. Parameters: mgd  Midgard connection [in]  classname  MgdSchema class name Returns: query builder, or NULL if the named class is not found Definition at line 315 of file query_builder.c. References _MidgardObjectClass::data, MidgardQueryBuilder::error, MidgardQueryBuilder::ext_type, MidgardQueryBuilder::include_deleted, MidgardQueryBuilder::join, MidgardQueryBuilder::lang, MidgardQueryBuilder::limit, MidgardQueryBuilder::link, MidgardQueryBuilder::mgd, MidgardQueryBuilder::offset, MidgardQueryBuilder::orders, MidgardQueryBuilder::parent_type, MidgardQueryBuilder::schema, MidgardQueryBuilder::stack, MidgardQueryBuilder::tables, MidgardQueryBuilder::type, MidgardQueryBuilder::types, and MidgardQueryBuilder::unset_lang. Referenced by midgard_collector_new(), midgard_import_object(), midgard_object_find(), midgard_object_get_by_guid(), midgard_object_get_by_id(), midgard_object_list(), midgard_object_list_children(), midgard_object_new(), and midgard_object_set_parameter().

void midgard_query_builder_set_lang (  MidgardQueryBuilder *  builder, gint  lang )

Sets internal lang used by Query Builder. Parameters: builder  query builder [in]  lang  Sets object's lang SQL query used by Query Builder will use set language explicitly. Objects in other languages will be not queried from database. Definition at line 494 of file query_builder.c. References MidgardQueryBuilder::lang.

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. Parameters: builder  query builder [in]  limit  query limit Definition at line 480 of file query_builder.c. References MidgardQueryBuilder::limit.

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. Parameters: builder  query builder [in]  offset  query offset Definition at line 487 of file query_builder.c. References MidgardQueryBuilder::offset.

void midgard_query_builder_unset_languages (  MidgardQueryBuilder *  builder  )

Unset all languages used by given Query Builder instance. Parameters: builder  MidgardQueryBuidler instance. All languages ( current and default one ) are unset for QB instance. SQL query is executed without language context. Definition at line 500 of file query_builder.c. References MidgardQueryBuilder::unset_lang.

---