TAKE
Return only as many rows as you need, and read a long table one page at a time.
Syntax
Give the number of rows to keep. Add a second number to skip rows first.
TAKE(limit)
TAKE(limit, offset)Parameters and arguments
limitThe most rows to return, as a whole number written in digits
Required: YesoffsetHow many rows to skip before the first is returned, as a whole number written in digits. The default is 0
Required: No
Examples
A short list from a long table.
Return type and behaviour
TAKE returns nothing itself. It limits the rows of the statement it belongs to. TAKE(0) returns no rows. A table with fewer rows than the limit returns what it has.
Without TAKE, a LOOKUP or GET returns every matching row.
Errors and exceptions
| Error | What happened | How to recover |
|---|---|---|
HTQL-5001 | TAKE was given more than two numbers | Write TAKE(limit) or TAKE(limit, offset) |
HTQL-1003 Unsupported syntax | The statement around TAKE is not written in HTQL's grammar | Check the other clauses |
Placement and context
Inside LOOKUP, TAKE is one of the function's arguments: the rows are ordered before TAKE keeps its share, wherever each is written among the arguments. Inside NEST, TAKE limits each parent's children. After GET or in a FOR body, TAKE is a step that cuts where it is written, and a statement may cut more than once: TAKE(100) in the database, then an IF, then TAKE(10) of what is left. See GET.
Limitations
- Not supported: a variable or an expression as the number, such as
TAKE(n)orTAKE(-1). Write the number itself, in digits. - A LOOKUP takes at most two numbers.
TAKE(1, 2, 3)is refused withHTQL-5001. - Give TAKE once in a statement. If it is repeated in a LOOKUP, the last one is used.
Permissions and security
TAKE grants no access of its own.
Best practices
- Add TAKE to any read of a table that can grow.
- Sort before you page, so each page continues where the last ended.
- Step the offset by the limit:
TAKE(25, 0), thenTAKE(25, 25), thenTAKE(25, 50).