Working with files

File

Attach a file to the query by URL. For attaching files you can use the built-in functions FilePath and FileContent. This PRAGMA is a universal alternative to attaching files using built-in mechanisms of web or console clients.

YQL reserves the right to cache files at the URL for an indefinite period, hence, if there is a significant change in the content behind it, we strongly recommend to modify the URL by adding or modifying dummy parameters.

If the token name is specified, its value will be used to access the target system.

FileOption

Set the option by the specified key for the specified file to the specified value. The file with this alias should already be declared through PRAGMA File or attached to the query.

Currently supported options:

Example:

PRAGMA FileOption("<file-name>", "bypass_artifact_cache", "true");

Library

Treat the specified attached file as a library from which you can do IMPORT. The syntax type for the library is determined from the file extension:

• .sql: For the YQL dialect of SQL (recommended).
• .yqls: For s-expressions.

Example with a file attached to the query:

PRAGMA library("a.sql");
IMPORT a SYMBOLS $x;
SELECT $x;

If the URL is specified, the library is downloaded from the URL rather than from the previously attached file as in the following example:

PRAGMA library("a.sql","https://raw.githubusercontent.com/ytsaurus/ytsaurus/refs/heads/main/yt/docs/code-examples/yql/pragma-library-example");
IMPORT a SYMBOLS $x;
SELECT $x;

In this case, you can use text parameter value substitution in the URL:

DECLARE $_ver AS STRING; -- "pragma-library-example"
PRAGMA library("a.sql","https://raw.githubusercontent.com/ytsaurus/ytsaurus/refs/heads/main/yt/docs/code-examples/yql/{$_ver}");
IMPORT a SYMBOLS $x;
SELECT $x;

Package

Attach a hierarchical set of files to the query by URL, treating them as a package with the specified name, an interrelated set of libraries.

The package name is expected in project_name.package_name format; package libraries can then be used to make IMPORT with a module name like pkg.project_name.package_name.maybe.nested.module.name.

Example for a package with a flat hierarchy consisting of two libraries, foo.sql and bar.sql:

PRAGMA package("project.package", "/path/to/package");
IMPORT pkg.project.package.foo SYMBOLS $foo;
IMPORT pkg.project.package.bar SYMBOLS $bar;
SELECT $foo, $bar;

In this case, you can use text parameter value substitution in the URL:

DECLARE $_path AS STRING; -- "path"
PRAGMA package("project.package", "{$_path}/to/package");
IMPORT pkg.project.package.foo SYMBOLS $foo;
IMPORT pkg.project.package.bar SYMBOLS $bar;
SELECT $foo, $bar;

OverrideLibrary

Interpret the specified attached file as a library and override one of the package libraries with it.

The file name should be in the format project_name/package_name/maybe/nested/module/name.EXTENSION, PRAGMA Library extensions are supported.

Example:

PRAGMA package("project.package", "/path/to/package");
PRAGMA override_library("project/package/maybe/nested/module/name.sql");

IMPORT pkg.project.package.foo SYMBOLS $foo;
SELECT $foo;