Skip to content

Commit f544820

Browse files
l-zeuchl-zeuch
committed
docs: migrate db funcs to header layout
Signed-off-by: Luca Zeuch <[email protected]>
1 parent acfae10 commit f544820

File tree

1 file changed

+155
-24
lines changed

1 file changed

+155
-24
lines changed

‎content/docs/reference/templates/functions.md‎

Lines changed: 155 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -167,33 +167,164 @@ Removes the given member from the given thread.
167167

168168
## Database
169169

170-
| **Function** | **Description** |
171-
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
172-
| `dbBottomEntries` pattern amount nSkip | Returns `amount (max 100)`top entries of keys determined by the `pattern` from the database, sorted by the numeric value in a ascending order, next by entry ID. |
173-
| `dbCount` (userID\|pattern\|query) | Returns the count of all database entries which are not expired. Optional arguments: if `userID` is given, counts entries for that userID; if `pattern`, only those keys are counted that match the given pattern; and if `query` is provided, it should be an sdict with the following keys:<ul><li>`userID` - only counts entries with that userID, defaults to counting entries with any userID.</li><li>`pattern` - only counts dbEntry keys with names matching the pattern given, defaults to counting entries with any name.</li></ul> |
174-
| `dbDel` userID key | Deletes the specified key for the specified value from the database. |
175-
| `dbDelByID` userID ID | Deletes database entry by its ID. |
176-
| `dbDelMultiple` query amount skip | Deletes `amount (max 100)` entries from the database matching the criteria provided. `query` should be an _sdict_ with the following options:<ul><li>`userID` - only deletes entries with the dbEntry field .UserID provided, defaults to deleting entries with any ID.</li><li>`pattern` - only deletes entry keys with a name matching the pattern given.</li><li>`reverse` - if true, starts deleting entries with the lowest values first; otherwise starts deleting entries with the highest values first. Default is `false`.</li></ul>Returns the number of rows that got deleted or an error. |
177-
| `dbGet` userID key | Retrieves a value from the database for the specified user, this returns DBEntry object. Does not fetch member data as user object for .User like `dbGetPattern`, `dbBottom/TopEntries` do. |
178-
| `dbGetPattern` userID pattern amount nSkip | Retrieves up to`amount (max 100)`entries from the database in ascending order. |
179-
| `dbGetPatternReverse` userID pattern amount nSkip | Retrieves`amount (max 100)`entries from the database in descending order. |
180-
| `dbIncr` userID key incrBy | Increments the value for specified key for the specified user, if there was no value then it will be set to `incrBy`. Also returns the entry's current, increased value. |
181-
| `dbRank` query userID key | Returns the rank of the entry specified by the user ID and key provided in the set of entries matching the criteria provided. `query` specifies the set of entries that should be considered, and should be a sdict with the following options:<ul><li>`userID` - only includes entries with that user ID, defaults to including entries with any user ID</li><li>`pattern` - only includes database's `key` entries with names matching the pattern given, defaults to counting entries with any name</li><li>`reverse` - if true, entries with lower value have higher rank; otherwise entries with higher value have higher rank. Default is `false`.</li></ul> |
182-
| `dbSet` userID key value | Sets the value for the specified `key` for the specific `userID` to the specified `value`. `userID` can be any number of type _int64_. <br><br>Values are stored either as of type _float64_ (for numbers, oct or hex) or as varying type in bytes (for _slices_, _maps_, _strings_ etc) depending on input argument. |
183-
| `dbSetExpire` userID key value ttl | Same as `dbSet` but with an expiration `ttl` which is an _int_ and represents seconds. |
184-
| `dbTopEntries` pattern amount nSkip | Returns `amount (max 100)`top entries of keys determined by the `pattern` from the database, sorted by the numeric value in a descending order, next by entry ID. |
185-
186-
Patterns are basic PostgreSQL patterns, not Regexp: An underscore `(_)` matches any single character; a percent sign
187-
`(%)` matches any sequence of zero or more characters.
170+
These functions help you interact with the [custom command database](/learn/intermediate/database).
188171

189-
{{< callout context="note" title="Note" icon="outline/info-circle" >}}
172+
### dbBottomEntries
173+
174+
```yag
175+
{{ $entries := dbBottomEntries <pattern> <amount> <nSkip> }}
176+
```
177+
178+
Returns up to `amount` entries from the database, sorted in ascending order by the numeric value, then by entry ID.
179+
180+
- `amount`: the maximum number of entries to return, capped at 100.
181+
- `pattern`: the PostgreSQL pattern to match entries against.
182+
- `nSkip`: the number of entries to skip before returning results.
183+
184+
### dbCount
185+
186+
```yag
187+
{{ $count := dbCount <userID|pattern|query> }}
188+
```
189+
190+
Returns the count of all matching database entries that are not expired.
191+
192+
The argument must be one of the following:
193+
- `userID`: count entries for the given user ID.
194+
- `pattern`: count only entries with keys matching the given pattern.
195+
- `query`: an sdict with the following (all optional) keys:
196+
- `userID`: only count entries with a matching UserID field. Defaults to all UserIDs.
197+
- `pattern`: only counts entries with keys matching the given pattern. Defaults to all keys.
198+
199+
### dbDelByID
200+
201+
```yag
202+
{{ dbDelByID <userID> <ID> }}
203+
```
204+
205+
Deletes a database entry under the given `userID` by its `ID`.
206+
207+
### dbDelMultiple
208+
209+
```yag
210+
{{ $numDeleted := dbDelMultiple <query> <amount> <nSkip> }}
211+
```
212+
213+
Deletes up to `amount` entries from the database matching the given criteria. Returns the number of deleted entries.
214+
215+
- `query`: an sdict with the following (all optional) keys:
216+
- `userID`: only delete entries with a matching UserID field. Defaults to all UserIDs.
217+
- `pattern`: only delete entries with keys matching the given pattern. Defaults to all keys.
218+
- `reverse`: whether to delete entries with the lowest value first. Default is `false` (highest value first).
219+
- `amount`: the maximum number of entries to delete, capped at 100.
220+
- `nSkip`: the number of entries to skip before deleting.
221+
222+
### dbDel
223+
224+
```yag
225+
{{ dbDel <userID> <key> }}
226+
```
227+
228+
Deletes the specified entry from the database.
229+
230+
### dbGetPatternReverse
231+
232+
```yag
233+
{{ $entries := dbGetPatternReverse <userID> <pattern> <amount> <nSkip> }}
234+
```
235+
236+
Retrieves up to `amount` entries from the database in descending order as a slice.
237+
238+
- `userID`: the user ID to retrieve entries for.
239+
- `pattern`: the PostgreSQL pattern to match entries against.
240+
- `amount`: the maximum number of entries to return, capped at 100.
241+
- `nSkip`: the number of entries to skip before returning results.
242+
243+
See [dbGetPattern](#dbgetpattern) for a function that retrieves entries in ascending order.
244+
245+
### dbGetPattern
246+
247+
```yag
248+
{{ $entries := dbGetPattern <userID> <pattern> <amount> <nSkip> }}
249+
```
250+
251+
Returns up to `amount` entries from the database in ascending order as a slice.
252+
253+
- `userID`: the user ID to retrieve entries for.
254+
- `pattern`: the PostgreSQL pattern to match entries against.
255+
- `amount`: the maximum number of entries to return, capped at 100.
256+
- `nSkip`: the number of entries to skip before returning results.
257+
258+
See [dbGetPatternReverse](#dbgetpatternreverse) for a function that retrieves entries in descending order.
259+
260+
### dbGet
261+
262+
```yag
263+
{{ $entry := dbGet <userID> <key> }}
264+
```
265+
266+
Returns the specified database entry.
267+
268+
### dbIncr
269+
270+
```yag
271+
{{ $newValue := dbIncr <userID> <key> <incrBy> }}
272+
```
273+
274+
Increments the value of the specified database entry by `incrBy`. Returns the new value as a floating-point number.
275+
276+
- `incrBy`: the amount to increment the value by. Must be a valid number.
277+
278+
### dbRank
279+
280+
```yag
281+
{{ $rank := dbRank <query> <userID> <key> }}
282+
```
283+
284+
Returns the rank of the specified entry in the set of entries as defined by `query`.
285+
286+
- `query`: an sdict with the following (all optional) keys:
287+
- `userID`: only include entries with the given user ID.
288+
- `pattern`: only include entries with keys matching the given pattern.
289+
- `reverse`: if `true`, entries with lower values have higher ranks. Default is `false`.
290+
291+
### dbSetExpire
292+
293+
```yag
294+
{{ dbSetExpire <userID> <key> <value> <ttl> }}
295+
```
296+
297+
Same as [dbSet](#dbset) but with an additional expiration `ttl` in seconds.
298+
299+
### dbSet
300+
301+
```yag
302+
{{ dbSet <userID> <key> <value> }}
303+
```
304+
305+
Sets the value for the specified `key` and `userID` to `value`.
306+
307+
- `value`: an arbitrary value to set.
308+
309+
### dbTopEntries
310+
311+
```yag
312+
{{ $entries := dbTopEntries <pattern> <amount> <nSkip> }}
313+
```
314+
315+
Returns up to `amount` entries from the database, sorted in descending order by the numeric value, then by entry ID.
316+
317+
- `pattern`: the PostgreSQL pattern to match entries against.
318+
- `amount`: the maximum number of entries to return, capped at 100.
319+
- `nSkip`: the number of entries to skip before returning results.
320+
321+
{{< callout context="caution" title="Caution: Storing Numerical Values" icon="outline/alert-triangle" >}}
190322

191-
**Note about saving numbers into database:** As stated above, database stores numbers as type _float64_. If you save a
192-
large number into database like an _int64_ (which IDs are), the value will be truncated. To avoid this behavior, you can
193-
convert the number to type _string_ before saving and later back to its original type when retrieving it. Example: `{{$v
194-
:= .User.ID}} {{dbSet 0 "userid" (str $v)}} {{$fromDB := toInt (dbGet 0 "user_id").Value}}`
323+
Numerical values are stored as floating-point numbers in the database; large numbers such as user IDs will lose
324+
precision. To avoid this, convert them to a string before writing to the database.
195325

196-
`dict` key values are also retrieved as _int64,_ so to use them for indexing one has to e.g. `index $x (toInt64 0)`
326+
Numerical `dict` keys are retrieved as an `int64`, therefore you'd have to write<br>
327+
`{{ $dict.Get (toInt64 N)}}` to retrieve the value associated with the numerical key `N`.
197328

198329
{{< /callout >}}
199330

0 commit comments

Comments
 (0)