The Query Builder is a browser-based graphical tool that allows users to create and edit filters without them having to become a developer and learn the DataSift Curated Stream Definition Language (CSDL). It started life as an internal project at DataSift where our staff quickly recognized its potential for making the users' lives easier; indeed, it has become very popular with users who like the visual approach to building filters. Despite its visual nature, the Query Builder is a serious tool that can be used to build complex CSDL filters without using DataSift's Code Editor.

If you want to try the Query Builder, log in to your DataSift account, create a new stream and choose the Query Builder as your filter editor.

Under the hood

The Query Builder is written in JavaScript.

It is an independent, embeddable module that anyone can add to their own web page, blog, or a web view in a desktop or mobile application. You can embed the system into third party applicationsand you, because it is configurable, you can create 'private label' versions that match the look and feel of existing pages on a site. Internally, the Query Builder uses an intermediate format called JCSDL to store your filter definitions. Users don't edit JCSDL by hand, it is generated by the Query Builder automatically and compiled into CSDL when you save your filters. Whenever you want to modify your filters created using the Query Builder, the JCSDL code will be updated and turned into CSDL automatically, after you save your changes.

It's Open Source!

Being developers ourselves, we understand how hard and expensive it is to write and test code. We want to help external developers integrate our code and services with their own projects and we have decided to release the Query Builder under an open source license. You are free to use it, modify it, distribute it, and integrate it into your own projects, free or commercial, as long as you follow the licensing terms. Some possible use cases (but certainly not the only ones) could be:

• Giving your employees an editor they can use to create queries for your customers.
• Integrating and skinning the Query Builder to match your company's brand.
• Creating a customized version of the Query Builder that includes additional functionality, such as pre-loaded query templates.
• Creating a customized version of the Query Builder that allows user to build queries for a limited set of targets only.

For more information, check our implementation and customization guidelines.

JavaScript Curated Stream Definition Language (JCSDL) is an internal variant of CSDL, the query language used to define filters on the DataSift platform. JCSDL combines CSDL with the Query Builder state data, which is stripped off when JCSDL is converted into CSDL and compiled. State data is used to restore the Query Builder configuration when you open your filters for editing and it is not meant to be editied by humans. JCSDL is versioned and the Query Builder uses checksums to verify code integrity and to prevent tampering.

The transition from JCSDL into CSDL is not reversible, if you convert JCSDL into CSDL you lose the Query Builder state, but you keep the CSDL code. You can still edit it in the CSDL Editor.

Note that JCSDL is now up to version 2.0, but the editor is backwards compatible with 1.0.

 

 

Related topics:

For an introduction to CSDL consult our Language Guide.

The DataSift Query Builder has been designed to be easily embeddable on any website, blog, or a mobile or desktop application with a web view. As a matter of fact, we embed it ourselves on our own website. You can do it yourself, as long as you follow our Open Source licensing terms.

Prerequisites

We have tried to make it as easy as possible to add the Query Builder to your site, but there are some steps you need to take yourself if you want to integrate the Query Builder into a web page, website, or project:
 

1. Read our introduction to the Query Builder and JCSDL.
    
2. Make sure that your development and deployment environments meet our basic requirements.
    
3. Decide how much customization you are going to do:
    
   • If you are planning on making only small changes to the way the Query Builder looks on your site, download the standard distribution archive.
      
   • If you want to modify the Query Builder beyond what can be achieved with the basic configuration options, clone or fork the Query Builder project on GitHub and use your repository to build your own installation. To create a local clone of the GitHub repository, use the following command:
     
     git clone https://github.com/datasift/editor.git
      

No matter how you are going to obtain your own copy of the Query Builder, it needs to be installed on your web server or embedded in your project. On a web server that usually means the root document directory or a directory used to store scripts.

Embedding the Query Builder

Once you have a copy of the Query Builder installed on your server, you should create a test page and embed the default configuration to make sure that it work and can communicate with DataSift.

Customizing the Query Builder

Once you can verify that the standard configuration of the Query Builder works, you can either leave it as it is or customize it. There are many ways of customizing the Query Builder, depending on what sort of changes you have in mind:

• If you want to modify the way the Query Builder looks, you will have to modify its CSS style sheets and possibly its graphical assets.
   
• When you want to change the initial state of the Query Builder or pre-populate it with queries you need to read the Query Builder configuration guide.
   

Changes that require modification of the source code should be done on a clone of a fork of the Query Builder project.

if you need examples of working code, have a look at the ones we provided on our site. Make sure you are logged in to your DataSift account when you try them:

• Saving queries
• Loading queries
• Styling the Query Builder
• Reducing functionality of the Query Builder
• Pre-loading queries into the Query Builder
• Advanced customization of the Query Builder
   

If you want to validate JSCDL you can use the standard /compile DataSift API endpoint.

What you see below is a fully-functional instance of the Query Builder embedded on this page. If you want to learn how to embed the Query Builder on your site, page, or blog, read our embedding guide and check the initialization example.

The Query Builder is distributed in two ways: as a ready to install package and in source form. Always try downloading and installing the packaged version first and only use the source code from the project's GitHub repository when you cannot accomplish what you want using the pre-made distribution package.

The ready to install, performance optimized (pre-minified) version of the Query Builder is available as a ZIP archive.

If you need more flexibility and access to the original source code, you can clone the project's repository from GitHub.

See the minimum requirements and browser compatibility.

You may copy, distribute or modify the Query Builder under the terms of MIT and GPL Version 2. See the full licencing information.

Downloadlatest stable release Github repository

 

Embedding the Query Builder is a three-step process. You need to:

• Download the official distribution package.
• Modify the source of the HTML pages you want to add the Query Builder to.
• Save the Query Builder files in a directory under the document root directory on your web server.
   

Installing the Query Builder

The Query Builder archive contains three kinds of files:

• JavaScript
• CSS
• icon sprites

You will need to decompress them and copy them into the jcsdl subdirectory under the document root directory on your server or elsewhere where you want to store them. Make sure you use a separate directory for all of the Query Builder's files and make a note of their location within your server's filesystem in the relation to the document root directory. Whenever you reference them in your HTML pages, their location should be given as relative to the document root and not the filesystem root directory. For example, if the document root directory is located in /var/www/docs and you store the Query Builder's files in /var/www/docs/jcsdl, when you reference jcsdl.css from an HTML page, you would refer to it with jcsdl/jcsdl.css and not /var/www/docs/jcsdl/jcsdl.css

Embedding the Query Builder in an HTML page

To embed the Query Builder in an HTML page you need to:

• Import the Query Builder code and style sheets.
• Add a container element for the Query Builder and give it a CSS id.
• Create a new instance of the Query Builder (JCSDLGui).

 

Example:

 

Once initialized, the Query Builder looks like this:

You can choose the initial state of your Query Builder:

• embed the Query Builder "empty" to let your users create new queries. That's the default behavior.
• pre-load the Query Builder with a JCSDL query to allow your users to modify existing queries.

You can configure the Query Builder in a number of ways. For a complete overview check out the Configuration options in the Developer Resources section.

Configure the Query Builder with a separate object

Create a configuration object with the properties you want to override.
 

Add a configuration option object as the second argument of the JCSDLGui constructor

Alternatively, you can pass the Query Builder's configuration options as JavaScript Object literals on initialization. The example below hides all of the Facebook targets and the Amazon content target:

If need be, you can use more than one instance of the Query Builder on the same page, each with a different configuration. For example, you could embed one Query Builder excluding all of the Facebook targets and another one without the Amazon content target.
 

You can also use the Query Builder as a jQuery plugin. In this case, the Query Builder is initialized in the following way:

Once the plugin is initialized, you can use it in the following way:

Notes

Almost all data displayed inside the Query Builder (the list of targets, available operators, as well as some configuration options for the input fields) is defined inside the JCSDLDefinition object. It is possible to overwrite this object to suit your requirements using the Definition property in the configuration options.

If you are using parameters to modify default attributes of the Query Builder you can use the JCSDL.onLoad function. This function gathers the parameters, makes a proper queue for them, and prevents the Query Builder from calling the same parameter more than once.

Almost all data that is displayed inside the Query Builder (the list of targets, available operators, and some configuration options for the input fields) is defined inside the JCSDLDefinition object. You can overwrite this object to suit your requirements. In our Developer Resources section you will find an overview of the properties defined in an object.

To overwrite the settings you will need to set the Definition property in the Query Builder configuration. The definition property accepts an object with the JCSDLDefinition properties that you want to overwrite. You could, for example, overwrite the default parameters for the Facebook source and change the slider for the like count target. By default the slider goes from a minimum value of 0 to a maximum of 10,000; its default value is 500 and the step is 10.

For example. you could initialize your Query Builder instance with the following definition options:

The example above will make the slider for the Facebook like count look like this:

In general, changes to the Query Builder's appearance or behavior can be implemented via its configuration options. We recommend that you avoid making changes to the Query Builder's source code unless you have exhausted all other options. If you do decide to alter the source code, remember that your changes will be overwritten whenever you update your installation of the Query Builder, so be sure to keep a note of any changes you make.

Possible cases when you might need to change your source code include:

• making your own distribution of the Query Builder with a custom jcsdl.definition.js file that better fits your customer's needs.
• extending the filter with a graphical representation of the value added services you provide on top of the DataSift platform.

In this case you can fork the Query Builder on GitHub. Even though there is no requirement for making your code available to other developers, we would like to strongly encourage you to do so. We've open sourced the Query Builder so that our developer community can freely extend and modify the project. If you publish your code under the same open source licenses that we have chosen, you are more likely you to create the best possible experience for your customers.

To help first-time users, we've integrated tooltips into the Query Builder. Click on Learn More below the filter elements to display the tooltip message in a popup window:

The Query Builder fetches the tooltip messages through a JSONP service call. By default, tooltips are served from DataSift's documentation site, but it is possible to customize the content of the tooltips. To do so you'll need to set up a JSONP service to serve your customized content.

By default, the tooltips follow the title conventions of target, operator, and argument lists on the DataSift documentation site, with periods replaced by dashes. The tooltip service URLs are of the following format:

http://dev.datasift.com/tooltip-endpoint/tooltip/retrieve?callback=jcsdlJSONP&id=twitter-mentions

DataSift uses Drupal for its documentation site. We serve the JSONP with the Field resource module, an extension for the Drupal service module that makes it possible to reuse (part of) the content in a documentation node to build a tooltip system. You could use a similar setup or make your own tooltip service in the technology of your choice. When you have a working web service, you can modify the definition options when initializing the Query Builder to use your own tooltip resource URLs.

If you just want to modify the base service URL, you can overwrite the targetHelpJsonpSource variable in the definition file.

You can also use the targetHelpUrl function in the definition file, which takes two arguments:

• target name (e.g. facebook.to.ids)
• the specific field info (whatever is under this specific target in the definition object)

This has a default behavior (described below), but can also be overwritten. The default behavior for this function is to insert replace the {target} part of the above URL into the target name (with "." changed to "-"). It also checks for a hardcoded url in the target's definition which takes precedence over the dynamic ones.

The default function looks like this:

When you want to change the Query Builder’s appearance you need to override its style sheet. While you could modify its own style sheet, that is not the recommended way. To make it easier to upgrade the Query Builder in the future, your modifications should be stored in a separate CSS file. For example, if you store them in a file called yourCustomJCSDLCssFile.css, you will have to inlude yourCustomJCSDLCssFile.css after you include jcsdl.min.css.

Example

For a more in-depth overview of the Query Builder theming options, take a look at the CSS resources page.

Once your implementation of the Query Builder is fully operational, it is time to connect it to our platform. You need to capture the JCSDL code generated by your users working with the Query Builder, pass it on to DataSift, capture the results and send them back to the person who created the filter. Remember that you have full freedom to implement your own solution here and you have full freedom of user management. That also means it is your responsibility to write the code that glues it all together.

It is not a difficult task, but there are a few things you need to be aware of and a simple example like the one we present in this document will help you understand what is going on.

We will be building a page that lets the user construct filters using the Query Builder and see the results without having to reload the page. We need the following components:

1. A server connected to the internet.

   An AWS EC2 micro instance will do just fine. In this example we will assume that you are running Ubuntu Linux, but the principles apply to any operating system.

2. Open ports 22, 80, and 8888 on your server.

   If you are using the Amazon AWS EC2 service, you will need to modify the inbound rules for the security group associated with your EC2 instance. You can do that via the AWS EC2 Management Console.

3. Install Apache.

   $ sudo apt-get install apache2

4. Install PHP5 along with the Apache PHP5 module, cURL, and JSON.

   $ sudo apt-get install php5 libapache2-mod-php5 php5-curl php5-json

5. Restart Apache.

   $ sudo apachectl restart

6. Instal Python.

   $ sudo apt-get install python2.7

7. Instal the Tornado HTTP server framework.

   See the TornadoWeb site for the installation instructions.

8. Copy our sample HTTP connector receiver code to your server.

   You will find a discussion of what that code does on our HTTP connector page.

9. Start the HTTP connector receiver in a separate terminal window.

   $ python ./connector-http-server.py

   The server prints out some basic debugging information when it receives interactions from DataSift. It is a handy sanity check and that is why it make sense to start it in a separate terminal window.

10. Copy the Query Builder source code archive to the document root directory of your HTTP server.

    In case of Apache running on Ubuntu it will be located in /var/www:

    $ cd /var/www

    $ sudo unzip editor-master.zip

    $ sudo mv editor-master/minified jcsdl

11. Copy index.html to the document root.

    Make sure to change the value of the yourHTTPServerURL variable to the actual URL of your server.

12. Copy call.php to the document root.

    Change the value of httpServer to the URL that the HTTP connector receiver is listening on. Do not forget to set your DataSift username and API key. This script makes two calls to the /compile and /push/create endpoints. Do not forget to call /push/delete when you are done experimenting. You will need the ids of the Push subscription you want to delete, use /push/get to obtain them.

13. Copy read.php to the document root.

14. Load index.html into your favorite web browser.

15. Create a new filter.

16. Click Save and Preview.

17. Wait five seconds and the interactions you filter for should appear under the Query Builder.

The Query Builder was designed and built with the broadest possible browser and content management system compatibility in mind. Because it is built as a self-contained module with as few dependencies as possible, in most circumstances the Query Builder should not conflict with any other jQuery or JavaScript code on the pages you add it to.

You will need to use jQuery 1.4.2 or later to run the Query Builder. When the Query Builder cannot find jQuery on the page you embed it on, it will try to download jQuery from the Google's CDN.

On the client side, the Query Builder requires one of the following browsers with JavaScript enabled:

• Firefox - 5+
• Internet Explorer 7+
• Safari - 4.1+
• Opera - 10.5+
• Chrome - 12+

Here are all the JavaScript resources used by the Query Builder.

File	Description
jcsdl.parser.js	Verifies the JCSDL input, creates appropriate filters from the input, handles errors, generates the filter's output code.
jcsdl.gui.logic.js	The Advanced Logic Editor is defined in this file.
jcsdl.gui.filtereditor.js	The single filter editor is defined in this file.
jcsdl.gui.templates.js	A .js file for the HTML template of the GUI.
jcsdl.gui.plugins.js	A .js with external features.
jcsdl.gui.js	Core of the editor that ties all elements together.
jcsdl.gui.inputs.js	The definition of all the input elements.
jcsdl.definition.js	List of all possible targets, their fields and their types.
jquery.ui.custom.min.js	jQuery UI plugin.
jquery.touchpunch.js	Touch punch jQuery plugin for touch enabled mobile devices.
jquery.tipsy.js	Tipsy jQuery plugin.
jquery.simulate.js	jQuery simulate plugin to simulate browser mouse and keyboard events.
crypto.md5.min.js	Collection of standard and secure cryptographic algorithms.

 

If you want to change the way the Query Builder looks, you will need to create a separate CSS style sheet that overrides the default CSS style sheet. While you could potentially use a modified version of the default CSS file that ships with the Query Builder, chances are that it would get overwritten when you update your installation. Using a separate CSS style sheet is the recommended method to customize the appearance of the Query Builder; altering the default style sheet should, in most cases, be unnecessary.

Here are the CSS resources used by the Query Builder:

File	Description
jcsdl.css	The style sheet for all the interface elements of the GUI.
jcsdl.scss	The SCSS file for the jcsdl.css.
jquery.ui.custom.min.css	The style sheet of the jQuery GUI plugins.
jcsdl.sprites.css	Defines the iocns used to represent targets.
jcsdl.sprites.scss	The SCSS file for the jcsdl.sprites.css.

 

The Query Builder uses the SCSS meta-language to generate the jcsdl.css file from the jcsdl.scss file. If you want to modify jcsdl.css, you need to modify jcsdl.scss, otherwise whatever changes you make to to jcsdl.css will be overwritten. Modifying jcsdl.css is not necessary in practice. Any style definitions can be overridden with a separate style sheet. The easiest way to accomplish this is to copy jcsdl.css, modify and rename it, and import after jcsdl.css.

Style Structure

By default, the Query Builder appears in a container <div> with the "jcsdl-container" class. The styles inside that <div> are divided the following four groups:

• The header
• The filter
• The footer
• The tooltip

The header

The header contains the following elements:

• The title in an H3 tag.
• A <div> with the Create New Filter action button ("jcsdl-mainview-mode" class).
• Two icons that let you switch between the collapsed and expanded view modes ("jcsdl-mainview-actions" class).

The filter

The filter has two states:

1. The filter configuration state. Filters are built in the jcsdl-filter-editor > jcsdl-steps container. The (multiple levels of) targets, operators and arguments are shown in a set of consecutively numbered containers (e.g. jcsdl-filter-step-number-0,1,2…). Tooltips appear when you hover over the icons used to build filters.
2. The filter presentation state. After you have saved a filter, the Query Builder shows the previously made filters one filter per line. The container <div>'s class is jcsdl-filter, it contains the descriptions of the layers of the filter, like Target (target), Field(s) (field), Operator(s) (operator), or Value(s) (value).

The footer

The footer contains a <div> for the current filter related actions (jcsdl-actions) like save (jcsdl-editor-save) and cancel (jcsdl-editor-cancel).

The tooltip

The tooltip part (<div>) is only visible, when the cursor is over an element that has a tooltip. The tooltip function uses the Tipsy jQuery plugin.

• The tooltip itself is in a container div with the tipsy class. It also gets a tipsy-(gravity code) class, "n", "e", "s", "w" -- the cardinal directions on a compass, that determines the place and position of the little arrow (tail) of the tooltip.
• The <div> with tipsy-arrow class can be used to style the arrow itself.
• The inner part of the tooltip has the tipsy-inner class.

Class	Description
jcsdl-edit	The main <div> of the editor.
jcsdl-container	The main container <div> of the editor.
jcsdl-advanced-container	The ADVANCED logic editor.
jcsdl-advanced-gui-container	The container for graphical editor of advanced logic.
jcsdl-advanced-gui	The graphical editor of advanced logic.
jcsdl-advanced-gui-arrow	Arrow for scrolling the graphical editor of advanced logic.
jcsdl-advanced-manual	The manual editor of advanced logic.
jcsdl-advanced-option	The "+ []" and "Manual Edit" buttons in the list of logic options, next to ALL/ANY.
jcsdl-logic-token	A token (or tile) representing one item in the graphical editor of advanced logic.
jcsdl-logic-help	The help icon inside the ADVANCED logic button.
jcsdl-btn	General class that defines how buttons inside the editor look (excluding the big "Save and Preview", "Save" and "Cancel" buttons.
jcsdl-mainview	The container <div> of the three (four) parts of the editor.
jcsdl-header	The main <div> of the header part.
jcsdl-mainview-mode	The <div> of the view mode selector buttons of the editor.
jcsdl-label	Label of the view mode selector.
jcsdl-mainview-mode-options	<div> of the selection options of the view mode selector.
jcsdl-mainview-mode-option	One option of the view mode selector.
jcsdl-mainview-actions	Container <div> for action buttons, like "Create new filter".
jcsdl-filters-logic	Container <div> for the options of the filter logic selector.
jcsdl-filters-logic-option (jcsdl-and)	'And' option of the filter logic selector.
jcsdl-filters-logic-option (jcsdl-or)	'Or' option of the filter logic selector.
jcsdl-footer	Main container of the footer part.
jcsdl-actions	<div> of the action buttons inside to footer block.
jcsdl-button, jcsdl-editor-save	The save and preview footer button.
jcsdl-mainview-actions	Container <div> for action buttons, like "Create new filter" inside the footer part.
jcsdl-add-filter	Add filter button in the footer.
jcsdl-filter-editor	The main <div> of the filter editor part.
jcsdl-steps	Container <div> for one level of the editor.
jcsdl-filter-step-number-X jcsdl-filter-step-target jcsdl-filter-target-field-wrap jcsdl-filter-value-input-field...	One row of the steps, is numbered by the jcsdl-filter-step-number-X class.
jcsdl-filters-list	The main <div> of the created filter list.
jcsdl-filter	One filter in the filter list.
jcsdl-filter-description	Description of the filter.
jcsdl-filter-info, target	Container <div> for the filter targets.
jcsdl-filter-target	One filter target.
jcsdl-filter-info, field	Container <div> for the filter fields.
jcsdl-filter-field	One filter field.
jcsdl-filter-info, operator	Container <div> for the filter operators.
jcsdl-filter-operator	One filter operator.
jcsdl-filter-info, value	Container <div> for the filter values.
jcsdl-filter-options	One filter value.

Visual Logic Editor

The Visual Logic Editor module contains:

• The graphical logic editor (where you can drag and drop tiles).
• The manual logic editor (where you can input your logical expression manually).
• The logic options: ALL / ANY / ADVANCED.
• Additional logic options for ADVANCED editor (+ [] and switching between Manual and Graphical Editor).
• When the Query Builder is initialized without a pre-loaded query, the filter area only shows a toggle that offers you the choice between the AND and OR logic mode for the filters. The two option classes are:
  • jcsdl-and
  • jcsdl-or
     

When the ADVANCED mode is active the whole Query Editor gets a class .jcsdl-advanced-on (specifically, the element with .jcsdl-mainview class).

Retina CSS

Note that now the editor is "Retina-Ready", that is, it will load higher resolution graphics for devices with retina displays (like the iPad, iPhone, MacBook Pro). This behavior is defined at the bottom of jcsdl.scss file using CSS Media Query to target devices with pixel ratio/density higher than 1.5.

Notes

1. The definitions of the CSS style that use images are stored into a separate file, jcsdl.sprites.scss (jcsdl.sprites.css). If you want to use your own custom images, you can use this file as a reference.
2. In the Minified version these statements are included in jcsdl.scss (jcsdl.css).
3. To change the icons displayed in the Query Builder, overwrite the JCSDL GUI sprite files. Make sure you match the exact dimensions and position of the images you replace. The Developer Resources section includes an overview of the sprite files.

The following table lists all image sprite resources used by the Query Builder.

file	description	thumbnail
elements.png	Main control elements.
elements@2x.png	Most of the control elements for Retina displays.
icons-sprite-fields.png	Contains the icon sprites of the filter elements in the second level.
icons-sprite-fields@2x.png	Target icons for Retina displays.
icons-sprite-fields-dbw.png	Icons for new targets, mainly "demographics", "Bit.ly" and "Wikipedia" related.
icons-sprite-fields-dbw@2x.png	Retina icons for the above.
icons-sprite-fields-lon.png	Icons for new targets, mainly "links", "opengraph" and "NewsCred".
icons-sprite-fields-lon@2x.png	Retina icons for the above.
icons-sprite-operators.png	Contains the operator sprites of the filters.
icons-sprite-operators@2x.png	Retina operator icons.
icons-sprite-other.png	Contains other icon sprites, for example for geo relevant functions.
icons-sprite-other@2x.png	Retina other icons.
icons-sprite-targets.png	Contains the first row of the filter creator block, the sources of the data.
icons-sprite-targets@2x.png	Retina data sources icons.
jquery.tipsy.small.png	Image for the tail of tipsy tooltips text bubbles.
loader.gif	An animated gif image for preloading.
maps-marker.png	The map marker for the geo-related filters.
select.png	The selector frame for the filter creator.
select@2x.png	Retina selector frame for the filter creator.
step_background.png	The lower background for the rows of the filter creator.

 

 

The following table shows the properties available for the configuration object. For more details, take a look at Configuring the Query Builder the page.

 

 

Property	Description
Property: animate Type: Integer Default:  200	Speed of animations in the Query Builder (in milliseconds).
Property: cancelButton Type: Boolean Default:  true	Adds or removes a cancel button on the stream creation interface. Tip: Set to false if you don't want your users to hide the Query Builder.
Property: googleMapsApiKey Type: String Default:  (empty)	Enter your Google Maps API Key here. Amongst other effects it allows you to monitor your Maps API usage. Highly advised.
Property: mapsOverlay Type: Object Default:  {strokeWeight: 0, fillColor: '#7585dd', fillOpacity: 0.5}	Object literal that is passed to all Google Maps overlay elements (rectangle box, circle and polygon) and is used to configure their visualization. Additional possible options are strokeColor and strokeOpacity.
Property: mapsMarker Type: String Default:  csdl/img/maps- marker.png	Path of the marker icon used on the maps. This can be configured here since this cannot be styled in CSS and since on some websites/in some applications the relative URL may not work. In most cases the default should work out of the box.
Property: hideTargets Type: Array Default:  []	If you want to hide specific targets from the Query Builder you can pass them here as an Array of Strings. The targets in this array will not be visible in the Query Builder. This also applies to any „children” of these targets, for example if you hide „facebook”, all its fields will be hidden. Other examples are "twitter.author” or "twitter.retweet.author”. You can target whole data sources or their specific fields, e.g. „facebook.og.by”. Example input format: ['facebook.og', 'myspace', 'interaction.type']
Property: definition Type: Object Default:  {}	This option can be used to override any of the default JCSDLDefinition variables. See this section for more info.
Property: save Type: Function(code) Default:  (empty)	Function that is called on the 'save' event in the Query Builder, when a user clicks the 'Save and Preview' button. It's first (and only) argument is the resulting JCSDL code (a string). In the function, this keyword represents the Query Builder instance.
Property: cancel Type: Function() Default:  hides the Query Builder	Function that is called on the 'cancel' event in the Query Builder, ie. when a user clicks the 'Cancel' button. It is called without any arguments. The keyword identifies the Query Builder instance.
Property: change Type: Function() Default:  (empty)	Function called whenever a change in the editor occurs that may cause a change of JCSDL.
Property: saveError Type: Function(error) Default:  (empty)	Function called whenever an error occurs during saving of the stream.
Property: invalidJCSDL Type: Function(code) Default:  (empty)	Function called when invalid JCSDL is loaded into the editor.
Property: viewModeChange Type: Function(mode) Default:  (empty)	Function called when user changes view mode of the main filters list.
Property: filterNew Type: Function() Default:  (empty)	Function called when user clicks on "Add new filter".
Property: filterEdit Type: Function(filter) Default:  (empty)	Function called when user starts to edit an existing filter.
Property: filterDelete Type: Function(filter) Default:  (empty)	Function called when user deletes a filter.
Property: filterSave Type: Function(filter) Default:  (empty)	Function called when user saves a filter.
Property: filterCancel Type: Function(filter) Default:  (empty)	Function called when user cancels adding or editing a filter.
Property: targetSelect Type: Function(target) Default:  (empty)	Function called when user selects a target.
Property: operatorSelect Type: Function(operator) Default:  (empty)	Function called when user selects an operator.
Property: caseSensitivityChange Type: Function(on) Default:  (empty)	Function called when user toggles case sensitivity in the filter editor.
Property: logicChange Type: Function(logic) Default:  (empty)	Function called when user changes the logic of the stream.
Property: logicError Type: Function(error) Default:  (empty)	Function called when there is an error in advanced logic expression.
Property: advancedLogicChange Type: Function(expression) Default:  (empty)	Function called when there is a change in the advanced logic.
Property: manualLogic Type: Function() Default:  (empty)	Function called when user opens manual advanced logic editor.
Property: manualLogicChange Type: Function(expression) Default:  (empty)	Function called when user changes something inside the manual advanced logic editor.
Property: graphicalLogic Type: Function() Default:  (empty)	Function called when user opens graphical advanced logic editor.
Property: graphicalLogicChange Type: Function(expression) Default:  (empty)	Function called when user changes something inside the graphical advanced logic editor.
Property: graphicalLogicTokenMove Type: Function(expression) Default:  (empty)	Function called when user moves a token or tile inside the graphical advanced logic editor.
Property: parenthesisAdd Type: Function(expression) Default:  (empty)	Function called when user adds parenthesis to the graphical advanced logic editor.
Property: parenthesisDelete Type: Function(expression) Default:  (empty)	Function called when user deletes parenthesis from the graphical advanced logic editor.
Property: logicOperatorSwitch Type: Function(expression) Default:  (empty)	Function called when user switches a logic operator tile from AND to OR or other way around inside the graphical advanced logic editor.

 

The following table shows the properties defined in the JCSDLDefinition object. To learn how to overwrite the defaults follow the explanation in the how-to section for Overwriting defaults in the Query Builder.

Target definitions

Property	Type	Used By	Description
Name	String	Builder	Human-friendly name of the target/field.
Icon	String	Builder	By default, the builder gives each target an icon with a corresponding name (CSS class). This property can override it.
Type	String	Builder, Parser, Input fields	The type of data accepted by the target (used by the parser).
Input	String	Builder	What input type is used by this target? Possible values are "text", "number", "slider", "select", "geo_box", "geo_radius", "geo_polygon". There is a special case (for the "geo" inputs) in which this property can be an Array of Strings of possible input fields. In this case the builder will create an additional step for the user to choose the appropriate input type.
Operators	Array	Builder	List of operators that can be chosen for this target field. If there is only one operator in the Array then the builder will automatically select and hide it.
CS	Boolean	Text Input	Whether the 'case sensitivity' toggle should be displayed.

Operator definitions

Operator	Label	Short Description
substr	Substring	Filter for a sequence of characters that form a word or part of a word.
contains_any	Contains words	Filter for one or more string values from a list of strings.
contains_near	Contains words near	Filter for two or more words that occur near to each other.
different	Different	Not equal to...
equals	Equals	Equal to...
'in'	'In'	Filter for one or more values from a list.
greaterThan	>=	Greater than...
lowerThan	<=	Lower than...
exists	Exists	Check whether a target is present.
regex_partial	Partial Regex	Filter for content by a regular expression that matches any part of the target.
regex_exact	Exact Regex	Filter for content by a regular expression that matches the entire target.
geo_box	Geo Box	Filter for content originating from geographical locations within a bounding box.
geo_radius	Geo Radius	Filter for content originating from geographical locations within a circle.
geo_polygon	Geo Polygon	Filter for content originating from geographical locations defined by a polygon with up to 32 vertices.

Additional configuration of input types:

Text input type

Attributes:

arrayOperators - array of the selectable operators
operator - Default selected operator

Default:

Number input type:

Attributes:

arrayOperators - array of the selectable operators
operator - Default selected operator

Default:

Select input type

Attributes:

operator -
sets - Defined sets of selectable lists with the values and names of the items

 

Default:

Slider input type

Attributes:

operator -
min - minimum value of the slider
max - maximum value of the slider
step - the value of one step on the slider
'default' - the default value on the slider
displayFormat -

Default:

Geo box input type

Attributes:

operators -
instructions - Short step by step intructions for the input field.

Default:

Geo radius input type:

Attributes:

operators -
instructions - Short step by step intructions for the input field.

Default:

Geo polygon input type

Attributes:

operators -
instructions - Short step by step intructions for the input field.

Default:

 

We want to help you use our platform. If you are having trouble using DataSift, here is the recommended plan of action:

DataSift Forums

Whatever your problem, it is likely that somebody else has run into it before and it may have been resolved already. For that reason, you should join our developer community forums. The official DataSift developer support forum is located at dev.datasift.com/discussions and you can ask questions about the Query Builder in our dedicated support section for the editor: dev.datasift.com/discussions/category/editor. Both DataSift employees and the DataSift developer community regularly check, update, and answer questions in the forum.

If you are having issues with the DataSift platform, or have a tip or advice for the DataSift developer community, post it there, but please search the previous discussions before opening a new thread.

The Query Builder is an open source project. To ensure maximum peer learning we do not provide support over email. Please post your questions on our support forum.

DataSift Support

Our Support help desk is available at support.datasift.com. This is primarily for subscription customers, but our support team will try to reply to every message received there.

If you have exhausted the above list of resources and feel confident your needs cannot be met there, or you need to speak directly to a support agent, or you have billing or account queries, contact the support team at support.datasift.com.

Full details of DataSift's support terms can be found on our Support Policy page.

To give developers maximum flexibility when they include the Query Builder in their project and to make sure that license issues would not prevent them from using it, the Query Builder is licensed under both the MIT and GPL Version 2 open source licenses.

Open source software and libraries that are distributed with the Query Builder are licensed as follows:

Project name	Project license pages
CryptoJS	custom
jQuery UI	MIT, GPL
jQuery.simulate	MIT, GPL
Tipsy	MIT
jQuery UI Touch Punch	MIT, GPL Version 2

The Query Builder also uses jQuery and Google Maps JavaScript API v3. These are not distributed with the Query Builder, but loaded from external sources.

To load a predefinded filter, you need to pass its JCSDL definition to the Query Builder and execute the loadJCSDL function with the query as a parameter. You can do this in several ways:

• Provide a text area into which a user can paste the JCSDL definition of a query.
• Hard code a JCSDL definition in your HTML code.
• Retrieve a JCSDL definition through an AJAX call (for example, from a database).

The following example shows how you can pre-load a hard-coded JCSDL query in the Query Builder.

Example

This code produces this result.

You can add your custom save action to the save button in the Query Builder. You could for example use the callback function connected to the button to submit the JCSDL using a POST request or another AJAX request to:

• Trigger an automatic compilation through the DataSift API.
• Store the state of the Query Builder in a database.
• Output the JCSDL query in a text field.

The following examples show respectively how you can retrieve the JCSDL code in a text type HTML element and how you can submit JCSDL through a POST request.

the JCSDL output generated by the Query Builder reflects the state of the editor, it can be loaded into the Query Builder to rebuild a previously created query.

You could load JCSDL dynamically from:

• a text area that prompts a user to submit a JCSDL query
• JCSDL code embedded in the HTML
• JCSDL loaded via AJAX
• a Javascript variable

Once the Query Builder has been initialized, you can load pre-created JCSDL code into it.

In the following example we will create an input field and a button to trigger the load function. A function than reads out the JSCDL code from the input field, and passes it to the Query Builder.

Here is an example HTML code, with the input field and load query button:

The Query Builder's look and behavior can be significantly modified via its configuration options. In the previous example, you've seen some simple modifications, now let's do something more advanced.

Example

In the following example we've changed the following default settings in the Query Builder:

• The animation speed.
• The min, max, and default value of the age selector.
• The map field selection color and stroke.
• The selectable languages and their names.

The result

When you embed the Query Builder, there are a couple of initialization options that allow you to change its appearance and behavior. For example:

• You can change the Query Builder's animation speed, or even remove it.
• You can overwrite the default map overlay options with the mapsOverlay property.

Example

In the example below, we set a red overlay with 30% opacity, and a 1px width white stroke. The default overlay has 50% opacity, has the #7585dd color, and no stroke.
 

Notes

You can find all of the Configuration options in the Developer Resources section.

Some users prefer to focus on a subset of the functionality of the DataSift platform. You can streamline the user experience by creating an instance of the Query Builder with reduced functionality. The following example shows how you can reduce the functionality of the Query Builder to only allow queries with a limited set of targets, options and inputs.

The result

The following example shows you how to change the way the Query Builder looks. You need to complete the following three steps:

1. Create a new CSS style sheet that contains modified styles.
   
   Use the default stylesheets as your starting point. Simply make copies of these files, rename them, and modify these copies without changing the originals. Here's a sample CSS sheet:
    
   
2. Copy the new CSS files to a directory other than jscdl.
    
3. Add the CSS import statements to the HTML code of the page you are going to add the Query Builder to.
   
   Make sure you import your new style sheets after the default ones. See example below:
   
   

One of the ways to enhance the user experience is to pre-load queries. You can see it in practice below. If you would like to learn how to do it yourself, read our configuration guide and check out the query pre-loading example. You can download the code used to create this demo.

The Query Builder can be customized to your customers' needs in many ways. One of them is offering reduced functionality to those customers who prefer to work with a subset of data sources available on the DataSift platform. If you want to see how that could work in practice, try creating a new filter using the instance of the Query Builder embedded below on this page. It only allows users to filter against 2channel or IMDb. If you would like to know more, read our configuration guide and check the reduced functionality example. You can download the code used to create this demo.

The Query Builder can be customized to your users' needs. For example, you may want to adjust the timing of the user interface animation. If you want to see for yourself how that changes the look and the behavior of the Query Builder, try to create a new filter using the instance of the Query Builder embedded below on this page. If you want to know more about customizing the Query Builder, read our configuration guide and refer to the advanced configuration example. You can download the code used to create this demo.

It is possible to modify the way the Query Builder looks to make it match the visual design of the page you embed it on. Here's an example of the Query Builder with modified styling. If you you want to learn more, read our styling guide. You can download the file used to create the demo below. You will also need support files.