Queries: Difference between revisions
moved from md-documentation |
New documentation of queries |
||
| Line 1: | Line 1: | ||
== Queries == | |||
Queries are a unified way to access different kinds of information of the Sunhill Framework. The query system is intended to be similar to database queries of laravel. The main difference is, that its possible to query entities that are not stored in a database. | |||
=== General usage === | |||
All queries have to define some standardized methods. These are described in general in the following. For details see the different types of queries. | |||
=== Terminology === | |||
Due the fact that queries could be performed on many entities there are some terms that are used: | |||
* '''record''' is a single entity (like a database entry, a tag, a class, a plugin, etc.) | |||
* '''records''' are all entities (or at least those that fit a certain criteria) | |||
==== Finalizing calls ==== | |||
All queries need a finalizing call, that indicates what information should be retrieved or what action should be performed. | |||
===== count() ===== | |||
Count returns the number of records of the given query. | |||
Example: | |||
SampleEntity::query()->count(); | |||
returns the number of all records of SampleEntity. | |||
Example: | |||
SampleEntity::query()->where('name','test')->count(); | |||
returns the number of SampleEntity Records that have the name 'test' | |||
===== first() ===== | |||
Returns the first record of the given query. Note: When there is no <code>order()</code> statement, the result could be unpredictable. If the given query return no records at all an exception is raised. | |||
Example: | |||
SampleEntity::query()->first(); | |||
Returns the first record of SampleEntity. | |||
SampleEntity::query()->where('name','test')->first(); | |||
Returns the first record of SampleEntity where the name is 'test'; | |||
SampleEntity::query()->where('name','not existing')->first(); | |||
Throws an exception when no record has the name 'non existing'. | |||
====== Column list ====== | |||
There is an optional parameter $fields to first() that could either take a single string or an array of strings. | |||
If $fields is a string only the result of that field is returned. | |||
Example: | |||
SampleEntity::query()->first('id'); | |||
Returns for example 1 | |||
If $fields is an array of strings a Collection object is returned where the elements represent the given fields. | |||
Example: | |||
SampleEntity::query()->first(['id','name']); | |||
Returns [1, 'test'] | |||
<!-- | |||
= Queries = | = Queries = | ||
The ORM-frameworks defines queries so that all entities (like tags, classes, attributes and so on) can be accessed the same way. The structure is oriented to the laravel QueryBuilder with some minor additions for dealing with the single entities. | The ORM-frameworks defines queries so that all entities (like tags, classes, attributes and so on) can be accessed the same way. The structure is oriented to the laravel QueryBuilder with some minor additions for dealing with the single entities. | ||
| Line 110: | Line 165: | ||
=== Fields/pseudo fields === | === Fields/pseudo fields === | ||
--> | |||
Revision as of 11:36, 4 September 2024
Queries
Queries are a unified way to access different kinds of information of the Sunhill Framework. The query system is intended to be similar to database queries of laravel. The main difference is, that its possible to query entities that are not stored in a database.
General usage
All queries have to define some standardized methods. These are described in general in the following. For details see the different types of queries.
Terminology
Due the fact that queries could be performed on many entities there are some terms that are used:
- record is a single entity (like a database entry, a tag, a class, a plugin, etc.)
- records are all entities (or at least those that fit a certain criteria)
Finalizing calls
All queries need a finalizing call, that indicates what information should be retrieved or what action should be performed.
count()
Count returns the number of records of the given query.
Example:
SampleEntity::query()->count();
returns the number of all records of SampleEntity.
Example:
SampleEntity::query()->where('name','test')->count();
returns the number of SampleEntity Records that have the name 'test'
first()
Returns the first record of the given query. Note: When there is no order() statement, the result could be unpredictable. If the given query return no records at all an exception is raised.
Example:
SampleEntity::query()->first();
Returns the first record of SampleEntity.
SampleEntity::query()->where('name','test')->first();
Returns the first record of SampleEntity where the name is 'test';
SampleEntity::query()->where('name','not existing')->first();
Throws an exception when no record has the name 'non existing'.
Column list
There is an optional parameter $fields to first() that could either take a single string or an array of strings. If $fields is a string only the result of that field is returned.
Example:
SampleEntity::query()->first('id');
Returns for example 1
If $fields is an array of strings a Collection object is returned where the elements represent the given fields.
Example:
SampleEntity::query()->first(['id','name']);
Returns [1, 'test']
