Skip to main content

READ

Deprecated version

This document refers to a deprecated version of the RQL programming language.

Please go here for documentation related to the latest supported version.

Reads a single file, detecting its format, schema, and any other properties required to read the file.

Syntax
READ(location,
sample_size := 10000,
cache := <default interval>,
retries := <default int>,
retry_interval := <default interval>,
http_method := "get",
http_body := null,
http_body_string := null,
http_headers := [],
http_args := [],
http_auth_cred_name := null,
http_token := null,
http_token_url := null,
http_client_id := null,
http_client_secret := null,
http_renew_token_use_basic_auth := false,
http_username := null,
http_password := null)

The optional sample_size specifies the number of "objects" to sample within the file. The definition of object depends on the file format. For instance, for CSV and Excel an object is a row. For JSON and XML, an object is an element.

If a large sample_size is used, the detection will take more time to complete, but has a higher chance of detecting the correct format. If a small sample_size is used, the detection will be faster but may not return the precise results. Suppose a column contains integers up to row number 10000. At row 10001, the number is too large to be an integer, but is a long. In this case, using sample_size 10000 will result on the wrong type being inferred, since RAW expects an integer when a long is required to read the entire table. This triggers a runtime error.

Similarly, suppose a column is non-nullable but at a certain row, a null value is present. If the detecting stopped before encountering the null value, it will erroneously infer the data as having non-nullable values only (which leads to faster execution times). This again triggers a runtime error.

To force the detection to read as many rows as possible, set sample_size to -1.

The optional arguments starting with http, like http_method, define specific http request options; refer to :ref:HTTP Optional Arguments <http_optional_args>. `.