Google Git
Sign in
eclipse / gerrit / www.eclipse.org / ditto / c98e3c25b773428bd1ba6fbbd58667751951dac1 / . / 2.0 / basic-rql.html
blob: 5d115edfef1a7765540f23141fc97d1fc2eb660f [file] [log] [blame]
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="description" content="">
<meta name="keywords" content="rqlprotocol, rql, query, filter, filtering, search">
<title> RQL expressions • Eclipse Ditto™ • a digital twin framework</title>
<link rel="stylesheet" href="css/syntax.css">
<link rel="stylesheet" type="text/css" href="//cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/modern-business.css">
<link rel="stylesheet" href="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" crossorigin="anonymous">
<link rel="stylesheet" href="css/customstyles.css">
<link rel="stylesheet" href="css/boxshadowproperties.css">
<link rel="stylesheet" href="css/theme-ditto.css">
<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Open+Sans:400,700|Source+Code+Pro:300,600|Titillium+Web:400,600,700">
<script src="//cdnjs.cloudflare.com/ajax/libs/jquery/2.1.4/jquery.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js" crossorigin="anonymous"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/anchor-js/2.0.0/anchor.min.js" crossorigin="anonymous"></script>
<script src="js/toc.js"></script>
<script src="js/customscripts.js"></script>
<script type="application/ld+json">
{
"@context": "http://schema.org",
"@type": "Organization",
"url": "https://eclipse.org/ditto/",
"logo": "https://eclipse.org/ditto/images/ditto.svg"
}
</script>
<link rel="icon" type="image/png" href="images/favicon-16x16.png" sizes="16x16">
<link rel="icon" type="image/png" href="images/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="images/favicon-96x96.png" sizes="96x96">
<link rel="alternate" type="application/rss+xml" title="Eclipse Ditto Blog" href="https://www.eclipse.org/ditto/feed.xml">
<!-- Eclipse Foundation cookie consent: -->
<link rel="stylesheet" type="text/css" href="//www.eclipse.org/eclipse.org-common/themes/solstice/public/stylesheets/vendor/cookieconsent/cookieconsent.min.css" />
<script src="//www.eclipse.org/eclipse.org-common/themes/solstice/public/javascript/vendor/cookieconsent/default.min.js"></script>
<script>
$(document).ready(function() {
$("#tg-sb-link").click(function() {
$("#tg-sb-sidebar").toggle();
$("#tg-sb-content").toggleClass('col-md-9');
$("#tg-sb-content").toggleClass('col-md-12');
$("#tg-sb-icon").toggleClass('fa-toggle-on');
$("#tg-sb-icon").toggleClass('fa-toggle-off');
});
});
</script>
</head>
<script>
(function(w,d,s,l,i){
w[l]=w[l]||[];
w[l].push({'gtm.start':
new Date().getTime(),event:'gtm.js'});
var f=d.getElementsByTagName(s)[0],
j=d.createElement(s),
dl=l!='dataLayer'?'&l='+l:'';
j.async=true;
j.src='https://www.googletagmanager.com/gtm.js?id='+i+dl;
f.parentNode.insertBefore(j,f);
})(window,document,'script','dataLayer','GTM-5WLCZXC');
</script>
<body>
<!-- Navigation -->
<nav class="navbar navbar-inverse navbar-fixed-top">
<div class="container topnavlinks">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-ditto-home" href="index.html">&nbsp;<img src="images/ditto_allwhite_symbolonly.svg" class="ditto-navbar-symbol" alt="Home"> <img src="images/ditto_allwhite_textonly.svg" class="ditto-navbar-symbol-text" alt="Eclipse Ditto™"></a>
</div>
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right">
<!-- toggle sidebar button -->
<!--<li><a id="tg-sb-link" href="#"><i id="tg-sb-icon" class="fa fa-toggle-on"></i> Nav</a></li>-->
<!-- entries without drop-downs appear here -->
<li><a href="blog.html">Blog</a></li>
<li><a href="intro-overview.html">Documentation</a></li>
<li><a href="http-api-doc.html">HTTP API</a></li>
<li><a href="sandbox.html">Sandbox</a></li>
<li><a href="https://github.com/eclipse/ditto" target="_blank">
<img src="images/GitHub-Mark-Light-32px.png" alt="Sources at GitHub">
</a></li>
<li><a href="https://github.com/eclipse/ditto-clients" target="_blank">
<img src="images/GitHub-Mark-Light-32px.png" alt="SDK sources at GitHub">SDKs
</a></li>
<li><a href="https://github.com/eclipse/ditto-examples" target="_blank">
<img src="images/GitHub-Mark-Light-32px.png" alt="Example sources at GitHub">examples
</a></li>
<!-- entries with drop-downs appear here -->
<!-- conditional logic to control which topnav appears for the audience defined in the configuration file.-->
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Links<b class="caret"></b></a>
<ul class="dropdown-menu">
<li><a href="https://projects.eclipse.org/projects/iot.ditto" target="_blank">Eclipse Ditto Project</a></li>
<li><a href="https://www.eclipse.org/forums/index.php/f/364/" target="_blank">Forum</a></li>
<li><a href="https://ci.eclipse.org/ditto/" target="_blank">Jenkins</a></li>
<li><a href="https://dev.eclipse.org/mhonarc/lists/ditto-dev/" target="_blank">Mailing list archives</a></li>
<li><a href="https://gitter.im/eclipse/ditto" target="_blank">Gitter.im chat</a></li>
</ul>
</li>
<!--comment out this block if you want to hide search-->
<li>
<!--start search-->
<div id="search-demo-container">
<input type="text" id="search-input" placeholder="search...">
<ul id="results-container"></ul>
</div>
<script src="//cdnjs.cloudflare.com/ajax/libs/simple-jekyll-search/0.0.9/jekyll-search.js" type="text/javascript"></script>
<script type="text/javascript">
SimpleJekyllSearch.init({
searchInput: document.getElementById('search-input'),
resultsContainer: document.getElementById('results-container'),
dataSource: 'search.json',
searchResultTemplate: '<li><a href="{url}" title="RQL expressions">{title}</a></li>',
noResultsText: 'No results found.',
limit: 10,
fuzzy: true,
})
</script>
<!--end search-->
</li>
</ul>
</div>
</div>
<!-- /.container -->
</nav>
<!-- Page Content -->
<div class="container">
<div id="main">
<!-- Content Row -->
<div class="row">
<!-- Sidebar Column -->
<div class="col-md-3" id="tg-sb-sidebar">
<ul id="mysidebar" class="nav">
<li class="sidebarTitle">
<label for="docVersion">Eclipse Ditto™ version:</label>
<div class="select-wrapper">
<select id="docVersion" name="docVersion">
<option value="">development</option>
<option value="2.0">2.0</option>
<option value="1.5">1.5</option>
<option value="1.4">1.4</option>
<option value="1.3">1.3</option>
<option value="1.2">1.2</option>
<option value="1.1">1.1</option>
<option value="1.0">1.0</option>
</select>
</div>
<div id="dev-warning">
<div markdown="span" class="alert alert-warning" role="alert" style="font-size:0.6em"><i class="fa fa-warning"></i> <b>Important:</b> This documentation reflects the latest 'development'. You might want to choose a released version.</div>
</div>
</li>
<li class="subfolders">
<a href="#"><span></span>Introduction</a>
<ul>
<li><a href="intro-overview.html">Overview</a></li>
<li><a href="intro-digitaltwins.html">Digital twins</a></li>
<li><a href="intro-hello-world.html">Hello world</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Release Notes</a>
<ul>
<li><a href="release_notes_200.html">2.0.0</a></li>
<li><a href="release_notes_151.html">1.5.1</a></li>
<li><a href="release_notes_150.html">1.5.0</a></li>
<li class="subfolders">
<a href="#"><span></span>Archive</a>
<ul>
<li><a href="release_notes_140.html">1.4.0</a></li>
<li><a href="release_notes_130.html">1.3.0</a></li>
<li><a href="release_notes_121.html">1.2.1</a></li>
<li><a href="release_notes_120.html">1.2.0</a></li>
<li><a href="release_notes_115.html">1.1.5</a></li>
<li><a href="release_notes_113.html">1.1.3</a></li>
<li><a href="release_notes_112.html">1.1.2</a></li>
<li><a href="release_notes_111.html">1.1.1</a></li>
<li><a href="release_notes_110.html">1.1.0</a></li>
<li><a href="release_notes_100.html">1.0.0</a></li>
<li><a href="release_notes_090.html">0.9.0</a></li>
<li><a href="release_notes_080.html">0.8.0</a></li>
<li><a href="release_notes_100-M2.html">1.0.0-M2</a></li>
<li><a href="release_notes_100-M1a.html">1.0.0-M1a</a></li>
<li><a href="release_notes_090-M2.html">0.9.0-M2</a></li>
<li><a href="release_notes_090-M1.html">0.9.0-M1</a></li>
<li><a href="release_notes_080-M3.html">0.8.0-M3</a></li>
<li><a href="release_notes_080-M2.html">0.8.0-M2</a></li>
<li><a href="release_notes_080-M1.html">0.8.0-M1</a></li>
<li><a href="release_notes_030-M2.html">0.3.0-M2</a></li>
<li><a href="release_notes_030-M1.html">0.3.0-M1</a></li>
<li><a href="release_notes_020-M1.html">0.2.0-M1</a></li>
<li><a href="release_notes_010-M3.html">0.1.0-M3</a></li>
<li><a href="release_notes_010-M1.html">0.1.0-M1</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Installation</a>
<ul>
<li><a href="installation-building.html">Building Ditto</a></li>
<li><a href="installation-running.html">Running Ditto</a></li>
<li><a href="installation-operating.html">Operating Ditto</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Basic concepts</a>
<ul>
<li><a href="basic-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Model entities</a>
<ul>
<li><a href="basic-thing.html">Thing</a></li>
<li><a href="basic-feature.html">Feature</a></li>
<li><a href="basic-policy.html">Policy</a></li>
<li><a href="basic-namespaces-and-names.html">Namespaces and Names</a></li>
<li><a href="basic-metadata.html">Thing Metadata</a></li>
<li><a href="basic-errors.html">Errors</a></li>
</ul>
</li>
<li><a href="basic-auth.html">Authentication and Authorization</a></li>
<li><a href="basic-messages.html">Messages</a></li>
<li><a href="basic-signals.html">Signals</a></li>
<li class="subfolders">
<a href="#"><span></span>Signal types</a>
<ul>
<li><a href="basic-signals-command.html">Command</a></li>
<li><a href="basic-signals-commandresponse.html">Command response</a></li>
<li><a href="basic-signals-errorresponse.html">Error response</a></li>
<li><a href="basic-signals-event.html">Event</a></li>
<li><a href="basic-signals-announcement.html">Announcement</a></li>
</ul>
</li>
<li><a href="basic-apis.html">APIs</a></li>
<li><a href="basic-connections.html">Connections</a></li>
<li><a href="basic-placeholders.html">Placeholders</a></li>
<li><a href="basic-changenotifications.html">Change notifications</a></li>
<li class="active"><a href="basic-rql.html">RQL expressions</a></li>
<li><a href="basic-enrichment.html">Signal enrichment</a></li>
<li><a href="basic-search.html">Search</a></li>
<li><a href="basic-acknowledgements.html">Acknowledgements / QoS</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Advanced concepts</a>
<ul>
<li><a href="advanced-data-by-pass.html">Data By-Pass</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Architecture</a>
<ul>
<li><a href="architecture-overview.html">Overview</a></li>
<li class="subfolders">
<a href="#"><span></span>Services</a>
<ul>
<li><a href="architecture-services-policies.html">Policies</a></li>
<li><a href="architecture-services-things.html">Things</a></li>
<li><a href="architecture-services-things-search.html">Things-Search</a></li>
<li><a href="architecture-services-connectivity.html">Connectivity</a></li>
<li><a href="architecture-services-concierge.html">Concierge</a></li>
<li><a href="architecture-services-gateway.html">Gateway</a></li>
</ul>
</li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>HTTP API</a>
<ul>
<li><a href="httpapi-overview.html">Overview</a></li>
<li><a href="httpapi-concepts.html">Concepts</a></li>
<li><a href="httpapi-search.html">Search</a></li>
<li><a href="httpapi-messages.html">Messages</a></li>
<li><a href="httpapi-protocol-bindings-websocket.html">WebSocket protocol binding</a></li>
<li><a href="httpapi-protocol-bindings-cloudevents.html">Cloud Events HTTP protocol binding</a></li>
<li><a href="httpapi-sse.html">Server sent events</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Connectivity API</a>
<ul>
<li><a href="connectivity-overview.html">Overview</a></li>
<li><a href="connectivity-manage-connections.html">Manage connections</a></li>
<li><a href="connectivity-protocol-bindings-amqp091.html">AMQP 0.9.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-amqp10.html">AMQP 1.0 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt.html">MQTT 3.1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-mqtt5.html">MQTT 5 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-http.html">HTTP 1.1 protocol binding</a></li>
<li><a href="connectivity-protocol-bindings-kafka2.html">Kafka 2.x protocol binding</a></li>
<li><a href="connectivity-mapping.html">Payload mapping</a></li>
<li><a href="connectivity-header-mapping.html">Header mapping</a></li>
<li><a href="connectivity-tls-certificates.html">TLS certificates</a></li>
<li><a href="connectivity-ssh-tunneling.html">SSH tunneling</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Client SDK</a>
<ul>
<li><a href="client-sdk-overview.html">Overview</a></li>
<li><a href="client-sdk-java.html">Java</a></li>
<li><a href="client-sdk-javascript.html">JavaScript</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>Ditto Protocol</a>
<ul>
<li><a href="protocol-overview.html">Overview</a></li>
<li><a href="protocol-twinlive.html">Twin/live channel</a></li>
<li><a href="protocol-specification.html">Specification</a></li>
<li><a href="protocol-specification-topic.html">Protocol topic</a></li>
<li><a href="protocol-specification-errors.html">Errors</a></li>
<li><a href="protocol-specification-things.html">Things group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-things-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-things-merge.html">Merge</a></li>
<li><a href="protocol-specification-things-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-things-delete.html">Delete</a></li>
<li><a href="protocol-specification-acks.html">Acknowledgements</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ search/messages</a>
<ul>
<li><a href="protocol-specification-things-search.html">Search</a></li>
<li><a href="protocol-specification-things-messages.html">Messages</a></li>
</ul>
</li>
<li><a href="protocol-specification-policies.html">Policies group</a></li>
<li class="subfolders">
<a href="#"><span></span>→ commands/events</a>
<ul>
<li><a href="protocol-specification-policies-create-or-modify.html">Create/Modify</a></li>
<li><a href="protocol-specification-policies-retrieve.html">Retrieve</a></li>
<li><a href="protocol-specification-policies-delete.html">Delete</a></li>
<li><a href="protocol-specification-policies-announcement.html">Announcement</a></li>
</ul>
</li>
<li><a href="protocol-bindings.html">Bindings</a></li>
<li><a href="protocol-examples.html">Examples</a></li>
<li class="subfolders">
<a href="#"><span></span>→ Things examples</a>
<ul>
<li><a href="protocol-examples-creatething.html">Create a Thing</a></li>
<li><a href="protocol-examples-deletething.html">Delete a Thing</a></li>
<li><a href="protocol-examples-modifything.html">Modify a Thing</a></li>
<li><a href="protocol-examples-retrievething.html">Retrieve a Thing</a></li>
<li><a href="protocol-examples-retrievethings.html">Retrieve multiple Things</a></li>
<li><a href="protocol-examples-modifypolicyid.html">Modify the Policy ID of a Thing</a></li>
<li><a href="protocol-examples-createattributes.html">Create Attributes</a></li>
<li><a href="protocol-examples-deleteattributes.html">Delete Attributes</a></li>
<li><a href="protocol-examples-modifyattributes.html">Modify Attributes</a></li>
<li><a href="protocol-examples-retrieveattributes.html">Retrieve Attributes</a></li>
<li><a href="protocol-examples-createattribute.html">Create a single Attribute</a></li>
<li><a href="protocol-examples-deleteattribute.html">Delete a single Attribute</a></li>
<li><a href="protocol-examples-modifyattribute.html">Modify a single Attribute</a></li>
<li><a href="protocol-examples-retrieveattribute.html">Retrieve a single Attribute</a></li>
<li><a href="protocol-examples-createthingdefinition.html">Create a Definition</a></li>
<li><a href="protocol-examples-deletethingdefinition.html">Delete a Definition</a></li>
<li><a href="protocol-examples-modifythingdefinition.html">Modify a Definition</a></li>
<li><a href="protocol-examples-retrievethingdefinition.html">Retrieve a Definition</a></li>
<li><a href="protocol-examples-createfeatures.html">Create Features</a></li>
<li><a href="protocol-examples-deletefeatures.html">Delete Features</a></li>
<li><a href="protocol-examples-modifyfeatures.html">Modify Features</a></li>
<li><a href="protocol-examples-retrievefeatures.html">Retrieve Features</a></li>
<li><a href="protocol-examples-createfeature.html">Create a single Feature</a></li>
<li><a href="protocol-examples-deletefeature.html">Delete a single Feature</a></li>
<li><a href="protocol-examples-modifyfeature.html">Modify a single Feature</a></li>
<li><a href="protocol-examples-retrievefeature.html">Retrieve a single Feature</a></li>
<li><a href="protocol-examples-createdefinition.html">Create Feature Definition</a></li>
<li><a href="protocol-examples-deletedefinition.html">Delete Feature Definition</a></li>
<li><a href="protocol-examples-modifydefinition.html">Modify Feature Definition</a></li>
<li><a href="protocol-examples-retrievedefinition.html">Retrieve Feature Definition</a></li>
<li><a href="protocol-examples-createproperties.html">Create Feature Properties</a></li>
<li><a href="protocol-examples-deleteproperties.html">Delete Feature Properties</a></li>
<li><a href="protocol-examples-modifyproperties.html">Modify Feature Properties</a></li>
<li><a href="protocol-examples-retrieveproperties.html">Retrieve Feature Properties</a></li>
<li><a href="protocol-examples-createproperty.html">Create a single Property</a></li>
<li><a href="protocol-examples-deleteproperty.html">Delete a single Property</a></li>
<li><a href="protocol-examples-modifyproperty.html">Modify a single Property</a></li>
<li><a href="protocol-examples-retrieveproperty.html">Retrieve a single Property</a></li>
<li><a href="protocol-examples-createdesiredproperties.html">Create desired Feature Properties</a></li>
<li><a href="protocol-examples-deletedesiredproperties.html">Delete desired Feature Properties</a></li>
<li><a href="protocol-examples-modifydesiredproperties.html">Modify desired Feature Properties</a></li>
<li><a href="protocol-examples-retrievedesiredproperties.html">Retrieve desired Feature Properties</a></li>
<li><a href="protocol-examples-createdesiredproperty.html">Create a single desired Property</a></li>
<li><a href="protocol-examples-deletedesiredproperty.html">Delete a single desired Property</a></li>
<li><a href="protocol-examples-modifydesiredproperty.html">Modify a single desired Property</a></li>
<li><a href="protocol-examples-retrievedesiredproperty.html">Retrieve a single desired Property</a></li>
<li><a href="protocol-examples-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ Things merge examples</a>
<ul>
<li><a href="protocol-examples-mergething.html">Merge a Thing</a></li>
<li><a href="protocol-examples-mergepolicyid.html">Merge the Policy ID of a Thing</a></li>
<li><a href="protocol-examples-mergeattributes.html">Merge Attributes</a></li>
<li><a href="protocol-examples-mergeattribute.html">Merge a single Attribute</a></li>
<li><a href="protocol-examples-mergethingdefinition.html">Merge a Definition</a></li>
<li><a href="protocol-examples-mergefeatures.html">Merge Features</a></li>
<li><a href="protocol-examples-mergefeature.html">Merge a single Feature</a></li>
<li><a href="protocol-examples-mergefeaturedefinition.html">Merge Feature Definition</a></li>
<li><a href="protocol-examples-mergeproperties.html">Merge Feature Properties</a></li>
<li><a href="protocol-examples-mergeproperty.html">Merge a single Property</a></li>
<li><a href="protocol-examples-mergedesiredproperties.html">Merge desired Feature Properties</a></li>
<li><a href="protocol-examples-mergedesiredproperty.html">Merge a single desired Property</a></li>
<li><a href="protocol-examples-errorresponses.html">Error responses</a></li>
</ul>
</li>
<li class="subfolders">
<a href="#"><span></span>→ Policies examples</a>
<ul>
<li><a href="protocol-examples-policies-createpolicy.html">Create a Policy</a></li>
<li><a href="protocol-examples-policies-deletepolicy.html">Delete a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicy.html">Modify a Policy</a></li>
<li><a href="protocol-examples-policies-retrievepolicy.html">Retrieve a Policy</a></li>
<li><a href="protocol-examples-policies-modifypolicyentries.html">Modify entries</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentries.html">Retrieve entries</a></li>
<li><a href="protocol-examples-policies-createpolicyentry.html">Create a single entry</a></li>
<li><a href="protocol-examples-policies-deletepolicyentry.html">Delete a single entry</a></li>
<li><a href="protocol-examples-policies-modifypolicyentry.html">Modify a single entry</a></li>
<li><a href="protocol-examples-policies-retrievepolicyentry.html">Retrieve a single entry</a></li>
<li><a href="protocol-examples-policies-modifysubjects.html">Modify subjects</a></li>
<li><a href="protocol-examples-policies-retrievesubjects.html">Retrieve subjects</a></li>
<li><a href="protocol-examples-policies-createsubject.html">Create a single subject</a></li>
<li><a href="protocol-examples-policies-deletesubject.html">Delete a single subject</a></li>
<li><a href="protocol-examples-policies-modifysubject.html">Modify a single subject</a></li>
<li><a href="protocol-examples-policies-retrievesubject.html">Retrieve a single subject</a></li>
<li><a href="protocol-examples-policies-modifyresources.html">Modify resources</a></li>
<li><a href="protocol-examples-policies-retrieveresources.html">Retrieve resources</a></li>
<li><a href="protocol-examples-policies-createresource.html">Create a single resource</a></li>
<li><a href="protocol-examples-policies-deleteresource.html">Delete a single resource</a></li>
<li><a href="protocol-examples-policies-modifyresource.html">Modify a single resource</a></li>
<li><a href="protocol-examples-policies-retrieveresource.html">Retrieve a single resource</a></li>
<li><a href="protocol-examples-policies-errorresponses.html">Error responses</a></li>
<li><a href="protocol-examples-policies-announcement-subjectDeletion.html">Announcement for subject deletion</a></li>
</ul>
</li>
<li><a href="protocol-examples-search.html">→ Search examples</a></li>
</ul>
</li>
<li><a href="sandbox.html">Sandbox</a></li>
<li><a href="presentations.html">Presentations</a></li>
<li><a href="glossary.html">Glossary</a></li>
<li><a href="feedback.html">Feedback</a></li>
<p class="external">
<a href="#" id="collapseAll">Collapse All</a> | <a href="#" id="expandAll">Expand All</a>
</p>
</ul>
<!-- this highlights the active parent class in the sidebar. this is critical so that the parent expands when you're viewing a page. This must appear below the sidebar code above. Otherwise, if placed inside customscripts.js, the script runs before the sidebar code runs and the class never gets inserted.-->
<script>$("li.active").parents('li').toggleClass("active");
</script>
</div>
<!-- Content Column -->
<div class="col-md-9" id="tg-sb-content">
<div class="post-header">
<h1 class="post-title-main">RQL expressions</h1>
</div>
<div class="post-content">
<!-- this handles the automatic toc. use ## for subheads to auto-generate the on-page minitoc. if you use html tags, you must supply an ID for the heading element in order for it to appear in the minitoc. -->
<script>
$( document ).ready(function() {
// Handler for .ready() called.
$('#toc').toc({ minimumHeaders: 0, listType: 'ul', showSpeed: 0, headers: 'h2,h3,h4' });
/* this offset helps account for the space taken up by the floating toolbar. */
$('#toc').on('click', 'a', function() {
var target = $(this.getAttribute('href'))
, scroll_target = target.offset().top
$(window).scrollTop(scroll_target - 10);
return false
})
});
</script>
<div id="toc"></div>
<p>Ditto utilizes a subset of <a href="#" data-toggle="tooltip" data-original-title="Resource Query Language">RQL</a>
as language for specifying queries.</p>
<p>The <a href="https://github.com/persvr/rql">RQL project page</a> says about it:</p>
<blockquote>
<p>Resource Query Language (RQL) is a query language designed for use in URIs with object style data structures. […]<br />
RQL can be thought as basically a set of nestable named operators which each have a set of arguments.
RQL is designed to have an extremely simple, but extensible grammar that can be written in a URL friendly query string.</p>
</blockquote>
<p>An example helps more than a thousand words, so that would be the example of a simple RQL query querying
for <code class="highlighter-rouge">foo="ditto"</code> and <code class="highlighter-rouge">bar&lt;10</code>:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>and(eq(foo,"ditto"),lt(bar,10))
</code></pre></div></div>
<p>That query consists of one <a href="#logical-operators">logical operator </a> <a href="#and">“and”</a>,
two <a href="#relational-operators">relational operators</a> of which each consists of a <a href="#query-property">property</a>
and a <a href="#query-value">value</a>.</p>
<p>The following sections describe what the RQL syntax is capable of.</p>
<h2 id="rql-filter">RQL filter</h2>
<p>The RQL filter specifies “what” to filter.</p>
<h3 id="query-property">Query property</h3>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;property&gt; = url-encoded-string
</code></pre></div></div>
<p>To filter nested properties, Ditto uses the JSON Pointer notation (<a href="https://tools.ietf.org/html/rfc6901">RFC-6901</a>).</p>
<p>The following example shows how to apply a filter for the sub property location of the parent property attributes with
a forward slash as separator:</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>eq(attributes/location,"kitchen")
</code></pre></div></div>
<h3 id="query-value">Query value</h3>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>&lt;value&gt; = &lt;number&gt;, &lt;string&gt;, true, false, null
&lt;number&gt; = double, integer
&lt;string&gt; = ", url-encoded-string, "
</code></pre></div></div>
<p><strong>Comparison of string values</strong></p>
<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> Comparison operators such as <code class="highlighter-rouge">gt</code>, <code class="highlighter-rouge">ge</code>, <code class="highlighter-rouge">lt</code> and <code class="highlighter-rouge">le</code>, do not support a special
“semantics” of string comparison (e.g. regarding alphabetical or lexicographical ordering).<br />
However, you can rely on the alphabetical sorting of strings with the same length (e.g. “aaa” &lt; “zzz”) and that the
order stays the same over multiple/different filter requests.</div>
<p><strong>Comparison of other data types</strong></p>
<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> Please note that the comparison of other data types is is supported by the API, but it
only supports comparison of same data types, and does not do any conversion during comparison.</div>
<h3 id="relational-operators">Relational operators</h3>
<p>The following relational operators are supported.</p>
<h4 id="eq">eq</h4>
<p>Filter property values equal to <code class="highlighter-rouge">&lt;value&gt;</code>.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>eq(&lt;property&gt;,&lt;value&gt;)
</code></pre></div></div>
<p><strong>Example - filter things owned by “SID123”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>eq(attributes/owner,"SID123")
</code></pre></div></div>
<h4 id="ne">ne</h4>
<p>Filter property values not equal to <code class="highlighter-rouge">&lt;value&gt;</code>.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ne(&lt;property&gt;,&lt;value&gt;)
</code></pre></div></div>
<p><strong>Example - filter things with owner different than “SID123”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ne(attributes/owner,"SID123")
</code></pre></div></div>
<p>The response will contain only things which <strong>do</strong> provide an owner attribute (in this case with value 0 or not SID123).</p>
<h4 id="gt">gt</h4>
<p>Filter property values greater than a <code class="highlighter-rouge">&lt;value&gt;</code>.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gt(&lt;property&gt;,&lt;value&gt;)
</code></pre></div></div>
<p><strong>Example - filter things with thing ID greater than “A000”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>gt(thingId,"A000")
</code></pre></div></div>
<h4 id="ge">ge</h4>
<p>Filter property values greater than or equal to a <code class="highlighter-rouge">&lt;value&gt;</code>.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ge(&lt;property&gt;,&lt;value&gt;)
</code></pre></div></div>
<p><strong>Example - filter things with thing ID “A000” or greater</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>ge(thingId,"A000")
</code></pre></div></div>
<h4 id="lt">lt</h4>
<p>Filter property values less than a <code class="highlighter-rouge">&lt;value&gt;</code>.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>lt(&lt;property&gt;,&lt;value&gt;)
</code></pre></div></div>
<p><strong>Example - filter things with thing ID lower than “A000”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>lt(thingId,"A000")
</code></pre></div></div>
<h4 id="le">le</h4>
<p>Filter property values less than or equal to a <code class="highlighter-rouge">&lt;value&gt;</code>.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>le(&lt;property&gt;,&lt;value&gt;)
</code></pre></div></div>
<p><strong>Example - filter things with thing ID “A000” or lower</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>le(thingId,"A000")
</code></pre></div></div>
<h4 id="in">in</h4>
<p>Filter property values which contains at least one of the listed <code class="highlighter-rouge">&lt;value&gt;</code>s.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>in(&lt;property&gt;,&lt;value&gt;,&lt;value&gt;, ...)
</code></pre></div></div>
<p><strong>Example - filter things with thing ID “A000” or “AB00” or “AZ99”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>in(thingId,"A000","AB00","AZ99")
</code></pre></div></div>
<h4 id="like">like</h4>
<p>Filter property values which are like (similar) a <code class="highlighter-rouge">&lt;value&gt;</code>.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>like(&lt;property&gt;,&lt;value&gt;)
</code></pre></div></div>
<p><strong>Details concerning the like-operator</strong></p>
<p>The <code class="highlighter-rouge">like</code> operator provides some regular expression capabilities for pattern matching Strings.<br />
The following expressions are supported:</p>
<ul>
<li>*endswith =&gt; match at the end of a specific String.</li>
<li>startswith* =&gt; match at the beginning of a specific String.</li>
<li>*contains* =&gt; match if contains a specific String.</li>
<li>Th?ng =&gt; match for a wildcard character.</li>
</ul>
<p><strong>Examples</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>like(attributes/key1,"*known-chars-at-end")
like(attributes/key1,"known-chars-at-start*")
like(attributes/key1,"*known-chars-in-between*")
like(attributes/key1,"just-som?-char?-unkn?wn")
</code></pre></div></div>
<h4 id="exists">exists</h4>
<p>Filter property values which exist.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>exists(&lt;property&gt;)
</code></pre></div></div>
<p><strong>Example - filter things which have a feature with ID “feature_1”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>exists(features/feature_1)
</code></pre></div></div>
<p><strong>Example - filter lamps which are located in the “living-room”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>and(exists(features/lamp),eq(attributes/location,"living-room"))
</code></pre></div></div>
<h3 id="logical-operators">Logical operators</h3>
<h4 id="and">and</h4>
<p>Ensure that all given queries match.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>and(&lt;query&gt;,&lt;query&gt;, ...)
</code></pre></div></div>
<p><strong>Example - filter things which are located on the “upper floor” in the “living-room”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>and(eq(attributes/floor,"upper floor"),eq(attributes/location,"living-room"))
</code></pre></div></div>
<h4 id="or">or</h4>
<p>At least one of the given queries match.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>or(&lt;query&gt;,&lt;query&gt;, ...)
</code></pre></div></div>
<p><strong>Example - filter all things located on the “upper floor”, and all things with location “living-room”</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>or(eq(attributes/floor,"upper floor"),eq(attributes/location,"living-room"))
</code></pre></div></div>
<h4 id="not">not</h4>
<p>Negates the given query.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>not(&lt;query&gt;)
</code></pre></div></div>
<p><strong>Example - filter things whose ID do not start with a common prefix</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>not(like(thingId,"org.eclipse.ditto:blocked*"))
</code></pre></div></div>
<h2 id="rql-sorting">RQL sorting</h2>
<p>The RQL sorting part specifies in which order the result should be returned.</p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sort(&lt;+|-&gt;&lt;property&gt;,&lt;+|-&gt;&lt;property&gt;,...)
</code></pre></div></div>
<ul>
<li>Use <strong>+</strong> for an ascending sort order (URL encoded character <strong>%2B</strong>)</li>
<li>Use <strong>-</strong> for a descending sort order (URL encoded character <strong>%2D</strong>)</li>
</ul>
<p><strong>Example - sort the list ascending by the thing ID</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sort(+thingId)
</code></pre></div></div>
<p><strong>Example - sort the list ascending by an attribute</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sort(+attributes/location)
</code></pre></div></div>
<p><strong>Example - multiple sort options</strong></p>
<div class="highlighter-rouge"><div class="highlight"><pre class="highlight"><code>sort(-attributes/location,+thingId)
</code></pre></div></div>
<p>This expression will sort the list descending by location attribute.<br />
In case there are multiple things with the same location attribute, these are sorted ascending by their ID.</p>
<h3 id="sorting-of-string-values">Sorting of string values</h3>
<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> Sorting does not support a special “semantics” of string comparison (e.g. regarding
alphabetical or lexicographical ordering). However, you can rely on the alphabetical sorting of strings with the
same length (e.g. “aaa” &lt; “zzz”) and that the order stays the same over multiple/different filter requests.</div>
<h3 id="sorting-of-other-values">Sorting of other values</h3>
<div class="alert alert-info" role="alert"><i class="fa fa-info-circle"></i> <b>Note:</b> Sorting does not support a special “semantics” of comparison for fields with values of
different data types (e.g. numbers vs. strings). However, you can rely on the fact that values of the same type are
sorted respectively.</div>
<div class="tags">
<b>Tags: </b>
<a href="tag_rql.html" class="btn btn-default navbar-btn cursorNorm" role="button">rql</a>
<a href="tag_protocol.html" class="btn btn-default navbar-btn cursorNorm" role="button">protocol</a>
</div>
</div>
<hr class="shaded"/>
<footer>
<div class="row">
<div class="col-lg-12 footer">
<div class="logo">
<a href="https://eclipse.org"><img src="images/eclipse_foundation_logo.svg" alt="Eclipse logo"/></a>
</div>
<p class="notice">
&copy;2021 Eclipse Ditto™.
Site last generated: May 17, 2021 <br />
</p>
<div class="quickLinks">
<a href="https://www.eclipse.org/legal/privacy.php" target="_blank">
&gt; Privacy Policy
</a>
<a href="https://www.eclipse.org/legal/termsofuse.php" target="_blank">
&gt; Terms of Use
</a>
<a href="https://www.eclipse.org/legal/copyright.php" target="_blank">
&gt; Copyright Agent
</a>
<a href="https://www.eclipse.org/legal" target="_blank">
&gt; Legal
</a>
<a href="https://www.eclipse.org/legal/epl-2.0/" target="_blank">
&gt; License
</a>
<a href="https://eclipse.org/security" target="_blank">
&gt; Report a Vulnerability
</a>
</div>
</div>
</div>
</footer>
</div>
<!-- /.row -->
</div>
<!-- /.container -->
</div>
<!-- /#main -->
</div>
</body>
</html>