Queries: Difference between revisions
+cat |
+ Link to "writing own queries" |
||
| Line 110: | Line 110: | ||
{{Note|If no entity matches the given condition nothing is done an no exception is raised}} | {{Note|If no entity matches the given condition nothing is done an no exception is raised}} | ||
==== insert(array $fields) ==== | |||
Inserts a new record in the list. | |||
== List of Queries == | == List of Queries == | ||
| Line 119: | Line 122: | ||
== Writing own queries == | == Writing own queries == | ||
For details about writing own queries see [[Writing own queries|here]]. | |||
<!-- | <!-- | ||
=== Query building === | === Query building === | ||
| Line 168: | Line 133: | ||
==== where()/whereNot()/orWhere()/orWhereNot() ==== | ==== where()/whereNot()/orWhere()/orWhereNot() ==== | ||
The same method as the QueryBuilder of laravel provides. These methods can take up to three parameters (key, relation and value). If the last one is omitted it is assumed that the relation is "=" and the second parameter means the value (Example ->where('id',2) is the same as ->where('id','=',2) | The same method as the QueryBuilder of laravel provides. These methods can take up to three parameters (key, relation and value). If the last one is omitted it is assumed that the relation is "=" and the second parameter means the value (Example ->where('id',2) is the same as ->where('id','=',2) | ||
== Classes::query() == | == Classes::query() == | ||
Revision as of 11:20, 8 October 2024
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.
Common query functions
As in QueryBuilder it is possible to build chains of request elements (like ->where('this','=','that')->orderBy('something')->offset(2)->limit(2)).
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)
Building a query
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'
A general note on first(), firstIfExists(), only() and get()
Return type
first() and get() return the entity or a list of entities respectively. Normally a single entity is a StdClass with the givel columns as elements. In some cases it is useful to retun a different object.
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 StdClass object is returned where the elements represent the given fields.
Example:
SampleEntity::query()->first(['id','name']);
Returns {id: 1, name: 'test'}
first(?string|?array $column_list = null)
Returns the first record of the given query.
Warning: 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'.
firstIfExists(?string|?array $column_list = null)
Returns the first record of the given query or null if none exists.
Warning: When there is no order() statement, the result could be unpredictable.
If the given query return no records at all null is returned.
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();
Null is returned.
get(?string|?array $column_list = null)
Returns all entities that match the given condition.
only(?string|?array $column_list = null)
The query must return exactly one result and this result is returned. Same as first() except that it raises an exception when no or more than one result is returned.
Example:
SampleEntity()::where('id','=',1)->only();
Returns the entity with the id 1 (or raises an exception when this id does not exist.
delete()
Deletes all entries that match the given condition or throws an exception if the entity is read only.
Example:
SampleEntity()::where('id','=',1)->delete();
Deletes the entity with the id 1.
Note: If no entity matches the given condition nothing is done an no exception is raised
update(array $fields)
Updates all entries that match the given condition or throws an exception if the entity is read only.
Example:
SampleEntity()::where('id','=',1)->update(['payload'=>'abc']);
Sets the field payload to "abc" on the entity with the id 1 .
Note: If no entity matches the given condition nothing is done an no exception is raised
insert(array $fields)
Inserts a new record in the list.
List of Queries
Writing own queries
For details about writing own queries see here.
