Welcome, guest Sign In

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 RESTful object containing the URL on which YQL would normally perform a GET request.
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. Creates a result instance, or returns an error
query(statement,hashmap) 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) 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.
y.rest 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.

Tip

The request global object is available as an instantiated y.rest instance with all values filled in.

Example:

Property / Object Description Returns
url Provides a URL endpoint to query string
queryParams Gets the hashmap of query parameters object
matrixParams Gets the hashmap of matrix parameters object
headers Gets the hashmap of headers object
query(hashmap) Adds all the query parameters based on key-name hashmap self
query(name,value) Adds a single query parameter. self
header(name,value) Adds a header to the request. self
matrix(name,value) Adds a matrix parameter to the request. self
path(pathsegment) Appends a path segment to the URI. self
get() Performs a GET request to the URL endpoint. This object is useful with SELECT statements. response object
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. response object
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. response object
del() Performs an HTTP DELETE. This object is useful with DELETE statements. response object
contentType(string)

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.

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

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.

REST object
accept(string)

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

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.

REST object

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:

As you see above, along with your request you should also set your response through the following properties:

Property Description Returns
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

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 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.

Example:

Property Description Returns
results The results. E4X object
diagnostics The diagnostics. E4X object

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.

Tip

The y.query method also accepts a hashed set of variables, useful for variable substitution on a parametrized query. Here is an example that allows you to substitute the URL on Yahoo! Finance:

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(string plaintext) Provides a cryptographically secure version 4 Universal Unique Identifier (UUID). Returns a UUID.

request Global Object

The request global object is essentially an instantiated y.rest instance with all values filled in.

response Global Object

The response global object allows you to determine how responses are handled.

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.

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

Copyright © 2009 Yahoo! Inc. All rights reserved. Copyright | Privacy Policy

Help us continue to improve the Yahoo! Developer Network: Send Your Suggestions