JavaScript Objects, Methods, and Variables Reference

As you add JavaScript within your execute sub-element, you can take advantage of the following global objects:

Object Description
y Global object that provides access to additional language capabilities.
request The request object is a global reference to the rest object that contains the URL on which YQL would normally perform a GET request. You cannot reference the rest object directly, so you need to use request or y.rest to access the rest object.
response Response object returned as part of the "results" section of the YQL response.

Let's discuss each of these three in detail.

y Global Object

The y global object contains methods that firstly provide the basic of YQL functionality within JavaScript. It also allows you to include YQL Open Data Tables and JavaScript from remote sources.

Method Description Returns
query(statement) Runs a YQL statement. A response object that contains a result instance or an error object
query(statement,params, timeout, callback) Prepares and runs a YQL statement. Execute will replace all @name fields in the YQL statement with the values corresponding to the name in the supplied hashtable. Creates a result instance, or returns an error
diagnostics Returns diagnostic information related to the currently executed script. Returns diagnostic information
use(url,namespace) Imports an external Open Data Table definition into the current script at runtime. -
include(url) Includes JavaScript located at a remote URL. Returns an evaluation of that include
exit() Stops the execution of the current script. -
rest(url, callback) Sends a GET request to a remote URL endpoint. -
xpath(object,xpath) Applies XPath to an E4X object. Returns a new E4X object
xmlToJson(object) Converts an E4X/XML object into a JSON object. JavaScript object
jsonToXml(object) Converts a JavaScript/JSON object into E4X/XML. E4X object
log(message) Creates a log entry in diagnostics. Returns the log entry within the diagnostics output associated with the current select statement
env(environment file) Includes an environment file for use with your JavaScript. Example:

y.env("http://datatables.org/alltables.env");

-
crypto Provides basic cryptographic functions for use within JavaScript. Example:

var md5string = y.crypto.encodeMd5("encode this string to md5");

Returns an encrypted string.
context Provides information about the context or environment that Javascript code is running in. Currently, one property is supported: context.table Returns the Open Data Table name where JavaScript within an execute element has run.
tidy (string html) Tidy and return provided HTML. Returns HTML that is run through HTML Tidy.
y.rest(url, callback) method

The y.rest method allows you to make GET requests to remote Web services. It also allows you to pass parameters and headers in your request and use a callback function to make asynchronous requests. See Making Asynchronous Calls with JavaScript Execute for more information about using the callback.

Parameters:

  • url <String> The URL endpoint to a query.
  • callback <Function> (Optional) The callback mechanism waits to receive returned results that it can then process. This callback function allows asynchronous calls because the function can wait for the returned results while y.rest is called again.

Returns: rest Object

Examples:

In the following code snippet, an HTTP GET request is made to example.com and the response is saved to data.

By passing a callback to y.rest to handle the returned response as seen here, you can make asynchronous calls.

Tip

The y.rest method supports "chaining", which means that you can construct and run an entire REST request by creating a "chain" of methods. Here is a hypothetical example:

When chained, the resulting request looks like this:

Note

Because JSON does not have a "root" node in most cases, all JSON responses from a remote Web service will be contained within a special json root object under response.results.

y.query(statement, params, timeout, callback) method

Perhaps you want to use YQL queries while still using JavaScript within YQL. y.query allows you to perform additional YQL queries within the execute sub-element.

Parameters:

  • statement <String> A YQL statement.
  • params <Object> The object can contain key-values that can be referenced in the YQL statement for variable substitution. In the example below, the @url variable in the passed YQL statement is replaced with the value associated with the url key of the params object.
  • timeout <Number> The number of milliseconds before the call times out.
  • callback <Function> The callback function to handle the returned response. See Making Asynchronous Calls with JavaScript Execute for more information about using the callback.

Returns: Object

The returned object contains the following properties:

Property Description Data Type
results The results. E4X object
diagnostics The diagnostics. E4X object
query The YQL statement that was passed as a parameter to y.query. string
timeout

Specifies the request timeout in milliseconds. This is useful when you want to cancel requests that take longer than expected.

None

Example:

In the following code snippet, y.query executes a statement that uses the html table to get Yahoo! financial data.

Below the y.query method is passed a callback function that allows asynchronous calls.

Queries called from y.query return and execute instantly. However, data is only returned when the results property is accessed. This feature allows you to make multiple, independent queries simultaneously that are then allowed to process before being returned together when the results property is accessed.

y.crypto functions

YQL provides several cryptographic functions for use within JavaScript. These functions reduce the need for external libraries and make YQL easier to use.

Example:

Function Description Returns
encodeHmacSHA256(String secret, String plaintext) Encrypts a string using HMAC-SHA256 encryption. Returns an encrypted string.
encodeHmacSHA1(String secret, String plaintext) Encrypts a string using HMAC-SHA1 encryption. Returns an encrypted string.
encodeMd5(String plaintext) Provides the MD5 hash of a string. Returns an MD5 hash.
encodeSha(String plaintext) Provides the SHA-1 hash of a string. Returns an SHA-1 hash.
encodeBase64(String plaintext) Performs Base64 encoding of a string. Returns an Base64 encoded string.
decodeBase64(String plaintext) Performs Base64 decoding of a string. Returns an Base64 decoded string.
uuid() Provides a cryptographically secure version 4 Universal Unique Identifier (UUID). Returns a UUID.

request Global Object

The request global object is essentially a reference to a rest object. You must use the request object, y.rest, or y.query to access the rest object.

rest Object

The rest object has properties and methods for getting information and making REST calls.

Properties
Property Description Data Type
headers Gets the hashmap of headers object
url Provides a URL endpoint to query string
queryParams Gets the hashmap of query parameters E4X object containing query parameters.
matrixParams Gets the hashmap of matrix parameters result object containing matrix parameters.
Methods
accept(content-type)

Specifies the type of content to send in the response using the Accept HTTP header. This tells YQL what kind of data format you want returned, as well as how to parse it.

Parameters:

  • content-type <String> The content type of the data being sent. For example: application/xml.

Returns: rest Object

Examples:

The following is an example of how you would specify JSON as the return format for data you send as XML:

Using the above example, YQL will convert XML to JSON prior to returning it in the response.

contentType(content-type)

Specifies the content-type of the data being sent. An example of a content-type is: application/json. This object is useful with INSERT and UPDATE statements.

Note

This method does not automatically convert one data format to another prior to sending it, so if you indicate one format in contentType but actually send another, your Web service may produce an error.

Parameters:

  • content-type <String> The content-type of the data being sent. An example of a content-type is: application/json.

Returns: rest Object

The following is an example of how you would specify XML as the data you are sending:

del()

Performs an HTTP DELETE. This object is useful with DELETE statements.

Parameters:

  • None

Returns: result Object

Examples:

In the below Open Data Table, the del() method is used to delete the Mixi voice status identified by the post ID. Using del() sends an HTTP DELETE request to the URL defined in the url element.

get()

Performs a GET request to the URL endpoint. This object is useful with SELECT statements.

Parameters:

  • None

Returns: result Object

Examples:

header(name, value)

Adds an HTTP header to the request.

Parameters:

  • name <String> The name of the HTTP header.
  • value <String> The value associated with the HTTP header.

Returns: rest Object

Examples:

The header method in this code snippet is used to pass authorization credentials to get a response.
matrix(name,value)

Adds a matrix parameter to the request.

Parameters:

  • name <String>
  • value <String>

Returns: rest Object

Examples:

The code snippet below posts the matrix parameters to flower_order_server.com.

Matrix parameters are attached to the URI resource like query parameters, but are delimited by a semicolon and not an ampersand and the matrix parameters are not separted from the URI resource by a question mark. The yql.rest call creates the following URL: http://flower_order_service.com;flower=roses;color=red

path(path_segment)

Appends a path segment to the URI.

Parameters:

  • path_segment <String> The path segment to add to a URI.

Returns: request Object

Examples:

post(content)

Performs an HTTP POST, using the value of the content, to the URL endpoint. This object is useful with INSERT, UPDATE, and DELETE statements.

Parameters:

  • content <String|Object> The data that is posted.

Returns: result Object

Examples:

put(content)

Performs an HTTP PUT, using the value of the content, to the URL endpoint. This object is useful with INSERT, UPDATE, and DELETE statements.

Parameters:

  • content <String | Object> The data that is used in a PUT request.

Returns: result Object

Examples:

query(key, value)

Adds a single query parameter.

Parameters:

  • key <String>
  • value <String>

Returns: request Object

Examples:

query(hashmap)

Adds all the query parameters based on key-name hashmap.

Parameters:

  • hashmap <Object>

Returns: request Object

Examples:

timeout(milli_seconds)

Specifies the request timeout in milliseconds. This is useful when you want to cancel requests that take longer than expected.

Parameters:

  • milli_seconds <Number> The number of seconds before your request times out.

Returns: None

Examples:

response Global Object

The response global object allows you to determine how responses are handled and is also used to set the value to the data you'd like to return, as an E4X object, a JSON structure, or simply a string.

Object Description
object Contains the results of your execute script. Set this value to the data you'd like to return, as an E4X object, a JSON structure, or simply a string.

result Object

The result object contains the results of your execute script.

The table below lists the properties of the result object.

Property Description Data Type
response Get the response from the remote service. If the response content type is not application/json or text/xml then YQL provides a string. If JSON or XML is specified, the E4X representation of the data is returned. E4X object or string
headers The headers returned from the response. object
status The HTTP status code. string
timeout Indicates if the call timed out. boolean
url The URL used to make the request. string

Global Variables

The following global variables are available for use within the execute element of YQL Open Data Tables:

Variable Description
input This global variable is available for each binding within the inputs element such as key, value, or map. For example, to call the first binding below you would use nameofid.

var mycontent = nameofid;

Important

If the id name uses an illegal identifier, such as the use of hyphens, you must instead use the inputs global variable.

When a map binding is present in the Open Data Table, the global variable is present as a named hashtable. Each value provided in the YQL statement is set in the hashmap.

inputs

This global variable is an array that contains each binding within the inputs element, along with its value. For example, to call the second binding above, you would use inputs[fieldname]:

var mycontent =inputs['field-name'];

Table of Contents