Adobe® Marketing Cloud

Data Workbench Query API

Contents

Data Workbench Query API.............................................................................................3Administration of Data Workbench Query API.......................................................................................................3

Licensing.........................................................................................................................................................................................................3

Enabling and Disabling API Requests..................................................................................................................................................3

Access Control..............................................................................................................................................................................................4

Load Balancing.............................................................................................................................................................................................4

Using a Query API Proxy...........................................................................................................................................................................5

Using the Data Workbench Query API.......................................................................................................................5

Request Types...............................................................................................................................................................................................5

The Data Workbench Query Language...............................................................................................................................................6

Output Formats............................................................................................................................................................................................7

The HTTP Protocol.......................................................................................................................................................................................8

Query API Reference.......................................................................................................................................................12

Schema Request formats.......................................................................................................................................................................12

Data Request Formats.............................................................................................................................................................................14

Response Status Line...............................................................................................................................................................................17

Server Configuration...............................................................................................................................................................................17

Sample Clients...........................................................................................................................................................................................18

Contact and Legal Information..................................................................................................................................18

Data Workbench Query APILast updated 12/19/2013

Data Workbench Query APIThe processed results of a dataset are usually made available through the graphical user interface of the data workbench clientand report server.

However, if you want access to results in their raw form for use in other ways, you can use the Query API to query a single DPUand return the results across all DPUs.

To use the API, a client sends an HTTP request to the data workbench server. This requires administration to license the API,enable API requests, balance the data load, and set up access control rights or a proxy server.

Administration of Data Workbench Query API

Follow these basic steps to implement the data workbench query API.

Licensing

The data workbench Query API is only enabled by the server if the server's certificate (server_cert.pem in the server'sCertificates folder) includes the line:

Product = Query API

If the server is not licensed for the API but the API is enabled (see Enabling and Disabling API Requests), then the following lineshows in the server's trace log when the server starts or when a profile is reprocessed:

Not enabling Query API (not licensed)

If your server license does not include a Query API line, please contact Adobe ClientCare.

Only one server with a Query API license is required when installing to a server cluster. However, if heavy query traffic is expectedusing the Query API, then sending all queries to a single server may overload that server.

Enabling and Disabling API Requests

By default, each server will enable the data workbench Query API if the server has been licensed.

When licensed, the line

Enabling Query API (licensed)

shows in the server's trace log.

To disable the API service for each profile, simply add the line:

Enable Query API = bool: false

in the Server.cfg file in the Dataset folder of the profile.

When the previous line is present, the following line shows in the trace log:

Not enabling Query API (disabled in Server.cfg)

The following is an example:Server = ServerConfig: Enable Query API = bool: false Sample Bytes = double: 250e6

3Data Workbench Query API

Access Control

Data workbench access control applies to API requests with the same requirements as all other services.

API requests are sent to either of the following URIs:

http://<server>/Profiles/<profile>/API.query

or

https://<server>/Profiles/<profile>/API.query

• <server> is the DNS name or IP address (and, optionally, the port number) of the data workbench server.• <profile> is the name of the profile.

For example, the following entry in Access Control.cfg lets users access the data workbench query API if they connectusing SSL, and the OU (Organizational Unit) field of their trusted certificate is set to Insight (data workbench) API Users. Seethe example below:0 = AccessGroup: Members = vector: 1 items 0 = string: OU:Insight API Users Name = string: All Insight API users Read-Only Access = vector: 0 items Read-Write Access = vector: 1 items 0 = string: /Profiles/MyProfile/API.query

Note: Refer to the Data Workbench Server Installation and Administration Guide for information about controlling accessto the data workbench server URI's.

Since the API provides full access to your company's data, proper access control is extremely important. The proper choice ofaccess control means whether group membership is defined by IP address, certificate fields such as CN or OU, and so on, dependson the circumstances, including, but not limited to, whether the requests are done through the internet or within the confinesof a protected private network.

If the data workbench servers and the end users are all inside a firewall, access control using IP address may be acceptable.However, under other circumstances, especially if the data workbench server needs to be accessed through the Internet, usingSSL and trusted certificates is absolutely required.

In some installations, setting up all your users' browsers to use trusted certificates may be impractical. A recommended solutionis to use a Query API Proxy.

Load Balancing

In a cluster, each licensed and enabled server can respond to API queries.

See Enabling and Disabling API Requests. The work of computing the query results is divided among all of the servers in thecluster. However, the server that received the query directly is burdened more than the other servers for both CPU and memoryusage.

When heavy API query traffic is expected—or when server status indicates that the API query server is significantly more heavilyloaded than the other servers in the cluster—it is advisable to balance the traffic load. For the Query API in data workbench,load balancing means directing API queries evenly to all servers in the cluster.

If clients connect directly to the API server, then two different types of mechanisms can be used:

Instruct users to employ different servers within the cluster when running a query. This is the simplest way to load balance.

4Data Workbench Query API

Give the client software a list of all servers in the cluster, then program it to select a different target server for each query (in arandom sequence).

If an API proxy is used, then employ Method 2 for load balancing. See Using a Query API Proxy.

Using a Query API Proxy

An API proxy is a web server (typically, a common HTTP server), which implement its own secure authentication scheme.

Most companies already have such a web server for use by their employees. The server receives requests from authenticatedusers and forwards them to the data workbench server. The proxy server makes the API query requests using SSL and a trustedcertificate.

A trusted certificate is issued by a CA listed in the trust_ca_cert.pem certificate, and found in the data workbench server'sCertificates folder.

In the Certificates folder there is a certificate called trust_ca_cert.pem, which contains a list of many well knownCertificate Authorities (CA). Any certificate you have is trusted if issued by one of those CA's.

An additional benefit of using an API proxy is the opportunity for the proxy to isolate the end user from the Query API protocol.

For example:

1. The server receives a regular HTTP request from the end user's browser:

(https://insight.mycompany.com/dashboard?date=yesterday).

2. The server submits the appropriate query to the data workbench query API.3. Search results are then formatted into HTML and returned to the user.

Using a Query API Proxy provides advantages over accessing the Query API directly using client-side javascript in the user'sbrowser. Client-side access through javascript is subject to browser exclusion of cross-domain scripting. This means that theweb server serving the page that contains the javascript should be on the same domain as the data workbench server, which isnot always practical.

Using the Data Workbench Query API

This section provides general information for employing the data workbench API Query including its request types, the querylanguage, output formats, and HTTP protocols.

In most cases, the body of the request consists of text written in the data workbench Query Language. It is assumed that you arefamiliar with the HTTP protocol. Users not familiar with HTTP may still be able to use the data workbench Query API throughone of the sample clients provided. See Sample Clients.

An API request is always related to a single profile.

Request Types

Two types of API requests are understood by the data workbench server:

• A Schema Request provides information about the dataset schema configured for the profile, similar to the informationdisplayed in the Dataset Schema visualization in the data workbench client. Please refer to the data workbench Client Guideand Dataset Configuration Guide for details.

• Data Requests query the server about the data processed.

5Data Workbench Query API

The data workbench Query API does not provide support for administration of the data workbench server. Although a handfulof metrics can be queried to provide a limited amount of information about the processing state of the server, any extensiveadministrative functionality is beyond the scope of this component.

Note: The API implemented in Insight 5.4 is not backwards compatible with previous versions. Any client code written forprevious versions of data workbench must be modified in order to be used with servers running the Insight 5.4 code.

The Data Workbench Query Language

This section describes the syntax and semantics of the data workbench Query Language.

The reader is assumed to be familiar with programming languages as well as with the terminology used to describe them.

Notation:

1. underlined words should be entered in the query text literally.2. UPPERCASE_WORDS represent the type of expression that should be used.3. The form {text}? represents optional text.

The data workbench Query Language is only used for Data Requests (not Schema Requests).

A query in the data workbench Query Language is a sequence of statements, each of which is either a definition statement or aquery statement. Each statement is terminated with a semicolon. White space is ignored outside of keywords, identifiers andstring literals.

A definition statement is used to define and name dimensions, metrics and filters. A collection of these objects is already initializedby the dataset configuration, and the Query Language definitions are used to add or override these definitions.

A query entity (dimension, metric or filter) defined in a definition statement is available for use in subsequent query statements(but only within the same request).

A definition statements has one of the following three forms:dim NAME = DIM_EXPR;metric NAME = METRIC_EXPR;filter NAME = FILTER_EXPR;

Dimensions, metrics and filters have separate name spaces, so a dimension, a metric, and a filter can have the same name andstill be recognized as distinct entities by the parser. (However, same names might confuse a person reading the code, and is notrecommended.)

For the syntax of DIM_EXPR, METRIC_EXPR and FILTER_EXPR, please refer to Query Language Syntax in the client guide.

Two kinds of queries can be described by a query statement:

• A Dim Query requests information about the current number and names of the elements of a dimension. The syntax of a DimQuery is:list DIM_EXPR {as STRING}? ;

• A Metric Query requests the result of evaluating a set of metrics over a dimension, optionally applying a given filter. The syntaxof a Metric Query is:eval METRIC_LIST over DIM_EXPR {as STRING}? ;

The optional "as STRING" clause in each of the query statement types assigns the given string as an alias for the dimension. Thisalias is used in the output, instead of the dimension's actual name. Using an alias allows outputting descriptive dimension names,which are not valid as identifiers within the API. A METRIC_LIST is one or more METRIC_EXPRs, separated by commas.

6Data Workbench Query API

Example

The following example shows a definition statement, two dim query statements and a metric query statement:dim WeekdayXReferrer = cartesian product(";", Day_of_Week, Referrer);list Referrer;list WeekdayXReferrer as "Weekday;Referrer";eval Visitors, Sessions over WeekdayXReferrer as "Weekday;Referrer";

About Report Time Dimensions

Report Time dimensions are defined in a dataset's configuration files and cannot be used as is in an API query. Report Timedimensions are those derived from the LastNDim, HoursOfLastDay or DaysOfLastMonth, and rely on the ReportTime metric.To use a Report Time dimension in an API query, it must be defined (or redefined) within the Query Language text. To facilitatesuch definition, the following dimensions and metrics are provided:

• Dimensions

• last n• days of previous months• days of current month• days of future months• hours of day

For details, refer to Query Language Syntax in the client guide.

• Metrics

• Now - A predefined Constant Metric, whose value is the time at which the query was parsed.• As_Of - This metric, which is generally available, is useful to refer to the latest time up to which all data has been processed.

Comments

The Query Language syntax does not currently support embedding comments within the query text.

Output Formats

The result provided in response to an API query can be formatted in one of a variety of formats.

The table below lists the formats currently supported.

See Schema Request Formats and Data Request Formats for the details of the representation in each format.

DescriptionFormat

All results are formatted as text, which is human readable and can be directly presented to the user. Thisformat is moderately space efficient.

Text

Numeric values are transmitted in their binary representation. This format is the most space efficient, and isalso the most efficient to create on the server side, and if the client wants to use numeric data for computations,

Binary

it can do so without having to parse the text. Supported for Data Requests only. All numeric values arerepresented as floating point numbers in the IEEE REAL*8 format, Little Endian byte order.

This format is the least space efficient, but is provided for the convenience of clients which use existing facilitiesto parse XML and convert them to native objects.

XML

7Data Workbench Query API

DescriptionFormat

Somewhat more efficient than XML. Provide for the convenience of clients which have existing facilities forparsing JSON.

JSON

The HTTP Protocol

The following sections identify responses and requests from the Query API.

API Server URI

An API request is always related to a single profile. API requests are sent to:

http:// <server> /Profiles/ <profile> /API.query or https:// <server> /Profiles/ <profile>/API.query

where <server> is the DNS name or IP address of the data workbench server and <profile> is the name of the profile. If acluster of servers is used, any of the DPUs in the cluster may be used. If many queries are submitted to a heavily loaded cluster,spread the queries evenly among the servers in the cluster, if practical.

API requests contain parameters in the HTTP request headers, or, alternatively, in the request's query string. Data requestscontains the query text in their body.

The response to an API request contains some information in the response headers. Most of this information is also availablewithin the response body. The actual results, if any, are returned in the response body.

Header names and their query string key equivalents are case sensitive, but their values are not, unless otherwise specified.

Response Status Line

Upon success, the server's response contains a status line of 200 OK. If a request is not valid, or if the server encountered anerror condition when trying to provide the response, a status line indicating the nature of the error is returned. See ResponseStatus Line.

Schema Requests

A Schema Request can be sent to the server as soon as the server has finished loading its configuration, and the result is sentimmediately in the HTTP response.

The parameters used in a Schema Request are:

DefaultRequiredValuesDescriptionQuery String KeyHeader

Yesget-schemaType of requestActionX-Action

textNotextFormat of resultFormatX-Format

xml

xml-flat

json

json-flat

8Data Workbench Query API

A Schema Request's body is left empty.

No special headers are used in the response to a schema request.

The result is returned as the body of the HTTP response to this request. See Schema Request Formats for additional information.

Data Requests

A data request provides a snapshot of the data processed by the server at a given time. Because updates for this snapshot mightbe desired, data is requested using a three phase protocol:

1. Create Request: Sends the query to the server, which creates an internal query object. The response to this request includesa unique Query ID, which is used later to refer to it in Result and Drop Requests. Multiple query objects may be created bymultiple Create Requests and retained by the server, each of which can be later referred to, using its Query ID.

2. Result Request: The client returns a snapshot of the results for the query identified by its Query ID. This can be repeatedindefinitely. If more than one query has been created, Result Requests for any or all of them can be interleaved arbitrarily(but each Result Request can only refer to a single Query ID).

3. Drop Request: The client sends a Drop Request when instructed. At this point the server destroys the query object and stopscalculating results for it, releasing the resources that are tied up in the calculation. The server also drops the requestautomatically if no Result Request has been received for a given query for a period of five minutes.

A Create Request may be combined with a Result Request, so that the response to the Create Request contains the [first] result.In this case, the request is referred to as a CreateWait Request.

Create Requests

The parameters used in a Create Request are:

DefaultRequiredValuesDescriptionQuery String KeyHeader

YescreateType of requestActionX-Action

textNoNoFormat of result. (Note:a subsequent Result

FormatX-Format

Request can override thisvalue.)

The body of the request contains the text of the query, which is expressed in the data workbench Query Language. See The DataWorkbench Query Language.

The response is returned immediately, without any query results.

The headers used in the response to a Create Request are:

When PresentDescriptionHeader

AlwaysA unique query identifier to be used in subsequent Result and Drop Requests.X-Query-ID

The body of the response to a Create Request consists of a single line, containing the Query-ID parameter to be used in subsequentResult and Drop requests. It is identical to the value of the X-Query-ID response header. Regardless of the requested resultsformat, this item is the only content of the body (not enclosed in XML tags or JSON syntax) and is always represented as text(not binary).

9Data Workbench Query API

Result Requests

The parameters used in a Result Request are:

DefaultRequiredValuesDescriptionQuery StringKey

Header

YesresultType of requestActionX-Action

YesThe value of theQuery-ID parameter

Identifies the query for whicha result is requested.

Query-IDX-Query-ID

returned by the serverin the response to theCreate or CreateWaitRequest.

Value specified inCreate Request.(Otherwise text)

Notext

xml

json

Format of result. (Note thatthis value will override thevalue specified in the CreateRequest, if any.)

FormatX-Format

binary

1.0NoA number in the range[0.0, 1.0] (inclusive)

The minimum completionlevel at which results will bereturned. A value of 0 will

CompletionX-Completion

always return the resultsimmediately.

The body of a Result Request is left empty.

The parameters used in the response to a Result Request are:

When PresentDescriptionHeader

AlwaysThe actual completion level of the results returned (Should always begreater than or equal to the value of the X-Completion header in therequest.)

X-Completion

If the status is "500 QueryError".

Additional information about the internal server error which caused a"500 Query Error" status.

X-Error

The body of the response to a Result Request contains the result. See Data Request Formats for more information.

CreateWait Requests

The parameters used in a CreateWait Request are:

DefaultRequiredValuesDescriptionQuery String KeyHeader

YescreatewaitType of requestActionX-Action

textNotextFormat of result. (Notethat this value will override

FormatX-Format

10Data Workbench Query API

DefaultRequiredValuesDescriptionQuery String KeyHeader

xmlthe value specified in theResult Request.) json

binary

1.0NoA number in the range[0.0, 1.0] (inclusive)

The minimum completionlevel at which results willbe returned.

CompletionX-Completion

This parameter affects thisrequest only, notsubsequent ResultRequests.

A value of 0 means thatresults will be returnedimmediately, regardless ofthe completion level of thequeries.

The body of the request contains the text of the query, which is expressed in the data workbench Query Language. See The DataWorkbench Query Language.

The response is delayed until the (explicit or implicit) value of the completion parameter is reached, and the body of the responsecontains the result.

The headers used in the response to a CreateWait Request are:

When PresentDescriptionHeader

AlwaysA unique query identifier to be used in subsequent Result and Drop Requests.X-Query-ID

AlwaysThe actual completion level of the results returned. (Will always be greaterthan or equal to the value of the X-Completion parameter in the request).

X-Completion

The body of the response to a CreateWait Request contains the results. See Data Request Formats for more information.

Drop Requests

The parameters used in a Drop Request are:

DefaultRequiredValuesDescriptionHeader

yesdropType of requestX-Action

yesThe value of the X-Query-ID headerreturned by the server in the response to theCreate Request.

Identifies the query to bedropped

X-Query-ID

11Data Workbench Query API

Query API Reference

The following appendixes provide request formats for the schema.

Schema Request formats

Text Format (X-Format: text)

The text format lets the client treat this data as a flat list of dimensions or to construct a hierarchical structure thereof.

The schema is represented as comma separated text, one dimension per line. Each line has four items:

DescriptionNameColumn

The name of this dimension.Name1

The name of the parent dimension (possibly empty, for a root dimension).Parent2

countable, simple, manyToMany or denormal.Relationship3

The type (class) of the dimension.Type4

XML Format (X-Format: xml)

The schema is represented hierarchically as XML. The following tags are used:

Child NodesAttributesDescriptionTag

Zero or more <DIM> tagsnoneTop level.<SCHEMA>

zero or one of each of the following<*_CHILDREN> tags:

name

type

Describes a dimension andits children.

<DIM>

<SIMPLE_CHILDREN>

<COUNTABLE_CHILDREN>

<MANY_TO_MANY_CHILDREN>

<DENORMAL_CHILDREN>

One or more <DIM> tagsnoneAll the simple children ofthe containing <DIM> node

<SIMPLE_CH ILDREN>

One or more <DIM> tagsnoneAll the countable childrenof the containing <DIM>node

<COUNTABLE_CHILDREN>

One or more <DIM> tagsnoneAll the many-to-manychildren of the containing<DIM> node

<MANY_TO_MANY_CHILDREN>

12Data Workbench Query API

Child NodesAttributesDescriptionTag

One or more <DIM> tagsnoneAll the denormal childrenof the containing <DIM>node

<DENORMAL_CHILDREN>

XML Flattened Format (X-Format: xml-flat)

This format is similar to the XML format, except <DIM> nodes do not contain children tags - all the <DIM> tags are containeddirectly in the top level <SCHEMA> tag.

Child NodesAttributesDescriptionTag

Zero or more <DIM> tagsnoneTop level<SCHEMA>

nonenameDescribes a dimension<DIM>

type

JSON Format (X-Format: json)

The schema is represented as an array in the JSON data-interchange format. Each element of the array is a dimension objectwith other objects and arrays nested as shown in the following table:

Members or Elements TypesDescriptionTypeObject

DimensionThe JSON container for the schemaArrayTop level

DescriptionTypeNameDescribes onedimension andits children

ObjectDimension

The name of this dimensionstringname

The type of this dimensionstringtype

All the simple children ofthis dimension

array ofDimensionobjects

simpleChildren

All the countable childrenof this dimension

array ofDimensionobjects

countableChildren

All the manyToManychildren of this dimension

array ofDimensionobjects

manyToManyChildren

All the denormal childrenof this dimension

array ofDimensionobjects

denormalChildren

13Data Workbench Query API

JSON Flattened Format (X-Format: json-flat)

This format is similar to the JSON format, except Dimension objects do not contain their children - all the Dimension objectsare contained directly in the top level array.

Members or Elements TypesDescriptionTypeObject

DimensionThe JSON container for the schemaArrayTop level

DescriptionTypeNameDescribes onedimension and itschildren

ObjectDimension

The name of this dimensionstringname

The type of this dimensionstringtype

Data Request Formats

The body of a Drop Request is empty.

The content of the response body for Create and Result Requests is shown below for the different formats.

Text Format (X-Format:text or Format=text)

Text formatted results consist of <TAB> separated, <CR><LF> terminated lines. The first line in this format is a header line,which contains data related to the complete request. This line is present in the response for both Create and Result requests. Itcontains two items, which are also available as response headers:

DescriptionResponse HeaderNameColumn

The unique ID assigned to this query when it was created.X-Query-IDQuery ID1

The completion level of this result, as a number in the range[0,1]. This is the minimum of the completion levels for allthe query statements in the request.

X-CompletionCompletion2

In the response to a Result or CreateWait request, following the heading line, the results for each query statement is given, inorder of the query statements.

The first line in of the result contains a single number, which is the number of result lines for this query statements (see exceptionbelow). The first item on each of the following lines is the name of the dimension elements. This is the only content of the linefor Dim Queries. For Metric Queries, the metric values for each metric are given, in the order listed in the query statement.

XML Format (X-Format:xml or Format=xml)

The result is represented hierarchically as XML. The following tags are used:

Child NodesAttributesDescriptionTag

One or more <DIM_QUERY>and/or <METRIC_QUERY > tags.

query_id - the unique ID assigned to thisquery when it was created.

The top level tag.<RESULT>

14Data Workbench Query API

Child NodesAttributesDescriptionTag

completion - The completion level of thisresult, as a number in the range [0,1]. Thisis the minimum of the completion levelsfor all the query statements in the request.

The values of these attributes are identicalto those of the X-Query-ID andX-Completion response headers,respectively.

zero or more <ELEMENT> tagsdim - the name of the dimension.The results for a dimquery.

<DIM_QUERY>

dim - the name of the dimensionover which the query is evaluated.

dim - the name of the dimension overwhich the query is evaluated.

The results for ametric query.

<METRIC_QUE RY>

METRIC (only within aMETRIC_QUERY tag)

ordinal - the ordinal number (index) of thiselement.

Describes anelement of thedimension.

<ELEMENT>

name - the name of the element.

nonename - the metric's name.The value of a singlequery for theelement.

<METRIC>

value - the metric's value for this element.

JSON Format (X-Format:json or Format=json)

The data is represented as an array in the JSON data-interchange format.

The first element of the array is an object which contains data related to the complete request. It has two members, which arealso available as response headers:

DescriptionResponse HeaderMember

The unique ID assigned to this query when it was created.X-Query-IDqueryId

The completion level of this result, as a number in the range [0,1]. This isthe minimum of the completion levels for all the query statements in therequest.

X-Completioncompletion

Members or Element TypesDescriptionTypeMember

n/aThe query type.DimQuery orMetricQuery

type

n/aThe dimension being describedor over which the metrics arebeing evaluated.

stringdim

string - element nameDescribes one dimension andits children.

ARRAYelements

15Data Workbench Query API

Members or Element TypesDescriptionTypeMember

DescriptionTypeNameThe results for a metric query(this element is omitted in dimqueries).

ARRAYmetrics

Each element of this array is theresult for one query statement,in the order they appear in therequest.

The name of thismetric.

stringname

The value of this metricfor each dimensionelement.

ARRAY ofstrings

values

Binary Format (X-Format:binary or Format=binary)

All numeric values are represented in Little Endian byte order.

Double values are represented as 8 byte floating-point numbers, using the IEEE REAL*8 format.

Int values are represented as 4 byte integers.

Int64 values are represented as 8 byte integers.

A string is represented as the string's 4-byte length (in bytes), followed by the characters, not NULLterminated. The strings arepassed through from the raw data, and their encoding is known to the system, but data workbench users are encouraged toprovide the data in the UTF-8 encoding.

The response body starts with a two element header:

double actualCompletionint64 Query-ID

Following the header, the results for each query statement is given, in the order of query statements in the query text.

Results of Dim Queries are represented as follows:

int nRowsint Cardinality

string name0

. . .

string namenRows-1

Results of Metric Queries are represented as follows:

int Cardinality

double valuenMetrics-1. . .double value0string name0

. . .

16Data Workbench Query API

double valuenMetrics-1. . .double value0string namenRows-1

Where:

• Query-ID is the unique ID assigned to this query when it was created.• actualCompletion is the completion level of this result, as a number in the range [0,1]. This is the minimum of the completion

levels for all the query statements in the request.• Cardinality is the number of elements of the dimension.• nRows is the number of dimension elements that are listed in the result. It will be either the same as the cardinality, or, in rare

cases, when names are not available, 0.• namei is the name of the i-th dimension element.• valuej is the result for the j-th metric for the corresponding dimension element.• nMetrics is the number of metrics in the metric query.

Response Status Line

The following response status line are returned by the server:

MeaningMessageStatus Code

Success.OK200

The body of a Create Request was empty.Empty Query400

The X-Action header was missing.No Action400

The value of the X-Action header was not recognized.Unrecognized Action400

The X-Query-ID header was missing from a Result or Drop Request.No Query-ID400

The value of the X-Query-ID header did not refer to an existingquery, possibly because that query had timed out.

Query Not Found400

The deprecated X-Language header was used with an unrecognizedvalue. This header should no longer be used.

Unrecognized query language400

The Query Language Parser detected an error in the queryBad Query: (followed by parser errormessage)

400

The value of the X-Format header was not recognized.Bad Format Requested: (followed by value)400

The value of the X-Completion header was not valid.Bad X-Completion: (followed by value)400

An internal server error has occurred while calculating the resultsof the query. See X-Error Create Requests.

Query Error500

Server Configuration

By default, the data workbench server accepts API requests for each profile (at the URL described in The HTTP Protocol). Thisaccess is subject to access control, as described in the data workbench Dataset Configuration Guide.

17Data Workbench Query API

To disable the API for a profile, the file server.cfg in the Dataset folder of that profile should contain the entry EnableQuery API with value set to false.

Sample Clients

Product releases include sample implementations of API clients.

HTML/Javascript Client

This sample client consists of three files:

• InsightAPI-Demo.html: A page containing a form with fields for the data workbench server name (or IP address), thename of the profile, and the query text.

• InsightAPI-Demo.js: Javascript source for this specific demo.• InsightAPI.js: A reusable set of Javascript classes for communicating with the data workbench server.

Perl Client

This sample client consists of three files:

• InsightAPI/Query.pm: A reusable module for communicating with the data workbench server.• example1.pl: A rudimentary demonstration of using the data InsightAPI::Query class.• example2.pl: A demonstration of different format outputs for schema and data queries.

Samples can be found on the Developer Connection site.

Contact and Legal Information

Information to help you contact Adobe and to understand the legal issues concerning your use of this product and documentation.

Help & Technical Support

The Adobe Marketing Cloud Customer Care team is here to assist you and provides a number of mechanisms by which theycan be engaged:

• Check the Marketing Cloud help pages for advice, tips, and FAQs• Ask us a quick question on Twitter @AdobeMktgCare• Log an incident in our customer portal• Contact the Customer Care team directly• Check availability and status of Marketing Cloud Solutions

Service, Capability & Billing

Dependent on your solution configuration, some options described in this documentation might not be available to you. Aseach account is unique, please refer to your contract for pricing, due dates, terms, and conditions. If you would like to add toor otherwise change your service level, or if you have questions regarding your current service, please contact your AccountManager.

Feedback

We welcome any suggestions or feedback regarding this solution. Enhancement ideas and suggestions for the Analytics suitecan be added to our Customer Idea Exchange.

18Data Workbench Query API

Legal

© 2013, AdobeAll rights reserved.Published by Adobe Systems Inc.

Terms of Use | Privacy Center

A trademark symbol (®, ™, etc.) denotes an Adobe trademark.

All third-party trademarks are the property of their respective owners. Updated Information/Additional Third Party CodeInformation available at http://www.adobe.com/go/thirdparty.

06052013

19Data Workbench Query API