Main Page » XQuery » Functions » Lazy Functions

Lazy Functions

This module contains functions for handling lazy items.

In contrast to standard XQuery items, a lazy item contains a reference to the actual data, and the data itself will only be retrieved if it is processed. Hence, possible errors will be postponed, and no memory will be occupied by a lazy item as long as its content has not been requested yet.

The following BaseX functions return…

Lazy Base64 binaries:
- fetch:binary
- file:read-binary
- db:get-binary
Lazy strings:
- fetch:text
- file:read-text

Some functions are capable of consuming the contents of lazy items in a streamable fashion: data will not be cached, but instead passed on to another target (file, the calling expression, etc.). The following streaming functions are currently available:

Archive Functions (most functions)
Conversion Functions: convert:binary-to-string
File Functions: file:write-binary, file:write-text (if no encoding is specified)
Database Functions: db:put-binary
Hashing Functions

The XQuery expression below serves as an example on how large files can be downloaded and written to a file with constant memory consumption:

file:write-binary('output.data', fetch:binary('https://files.basex.org/xml/xmark111mb.zip'))

If lazy items are serialized, they will be streamed as well.

Conventions

All functions and errors in this module are assigned to the http://basex.org/modules/lazy namespace, which is statically bound to the lazy prefix.

Functions

`lazy:cache`

Signature

Signature	lazy:cache( $input as item(), $lazy as xs:boolean? := false() ) as item()
Summary	Caches the data of lazy `$input` items: data of lazy items are retrieved and cached inside the item. non-lazy items, or lazy items with cached data, are simply passed through. If `$lazy` is set to `true()`, caching is deferred until the data is eventually requested. Streaming will be disabled: Data will be cached before a stream is returned. Caching is advisable if an item is processed more than once, or if the data may not be available anymore at a later stage.
Examples	`let $file := 'data.txt' let $text := lazy:cache(file:read-text($file)) return (file:delete($file), $text)` In the example, a file is deleted before its content is returned. To avoid a “file not found” error when serializing the result, the content must be cached.

lazy:cache(
  $input  as item()*,
  $lazy   as xs:boolean?  := false()
) as item()*

Summary

Caches the data of lazy $input items:

data of lazy items are retrieved and cached inside the item.
non-lazy items, or lazy items with cached data, are simply passed through.
If $lazy is set to true(), caching is deferred until the data is eventually requested. Streaming will be disabled: Data will be cached before a stream is returned.

Caching is advisable if an item is processed more than once, or if the data may not be available anymore at a later stage.

Examples

let $file := 'data.txt'
let $text := lazy:cache(file:read-text($file))
return (file:delete($file), $text)

In the example, a file is deleted before its content is returned. To avoid a “file not found” error when serializing the result, the content must be cached.

`lazy:is-lazy`

Signature	lazy:is-lazy( $item as item() ) as xs:boolean
Summary	Checks whether the specified `$item` is lazy.

`lazy:is-cached`

Signature	lazy:is-cached( $item as item() ) as xs:boolean
Summary	Checks whether the contents of the specified `$item` are cached. The function will always return `true` for non-lazy items.

Changelog

Version 9.1

Updated: lazy:cache: $lazy argument added; support for sequences.

Version 9.0

Added: lazy:is-cached
Updated: Renamed from Streaming Functions to Lazy Functions.

Version 8.0

Updated: stream:materialize extended to sequences.

Version 7.7

Added: New module added.

⚡Generated with XQuery