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

  • limit

    The most rows to return, as a whole number written in digits

    Required: Yes
  • offset

    How 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
ErrorWhat happenedHow to recover
HTQL-5001TAKE was given more than two numbersWrite TAKE(limit) or TAKE(limit, offset)
HTQL-1003 Unsupported syntaxThe statement around TAKE is not written in HTQL's grammarCheck 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) or TAKE(-1). Write the number itself, in digits.
  • A LOOKUP takes at most two numbers. TAKE(1, 2, 3) is refused with HTQL-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), then TAKE(25, 25), then TAKE(25, 50).