<!DOCTYPE html><html><head><title>Events Modeling</title><meta charset="utf-8"/><meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><meta class="swiftype" name="title" data-type="string" content="Events Modeling"/><link rel="canonical" href="https://predictionio.apache.org/datacollection/eventmodel/"/><link href="/images/favicon/normal-b330020a.png" rel="shortcut icon"/><link href="/images/favicon/apple-c0febcf2.png" rel="apple-touch-icon"/><link href="//fonts.googleapis.com/css?family=Open+Sans:300italic,400italic,600italic,700italic,800italic,400,300,600,700,800" rel="stylesheet"/><link href="//maxcdn.bootstrapcdn.com/font-awesome/4.2.0/css/font-awesome.min.css" rel="stylesheet"/><link href="/stylesheets/application-eccfc6cb.css" rel="stylesheet" type="text/css"/><script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.2/html5shiv.min.js"></script><script src="//cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script><script src="//use.typekit.net/pqo0itb.js"></script><script>try{Typekit.load({ async: true });}catch(e){}</script></head><body><div id="global"><header><div class="container" id="header-wrapper"><div class="row"><div class="col-sm-12"><div id="logo-wrapper"><span id="drawer-toggle"></span><a href="#"></a><a href="http://predictionio.apache.org/"><img alt="Apache PredictionIO" id="logo" src="/images/logos/logo-ee2b9bb3.png"/></a><span>®</span></div><div id="menu-wrapper"><div id="pill-wrapper"><a class="pill left" href="/gallery/template-gallery">TEMPLATES</a> <a class="pill right" href="//github.com/apache/predictionio/">OPEN SOURCE</a></div></div><img class="mobile-search-bar-toggler hidden-md hidden-lg" src="/images/icons/search-glass-704bd4ff.png"/></div></div></div></header><div id="search-bar-row-wrapper"><div class="container-fluid" id="search-bar-row"><div class="row"><div class="col-md-9 col-sm-11 col-xs-11"><div class="hidden-md hidden-lg" id="mobile-page-heading-wrapper"><p>PredictionIO Docs</p><h4>Events Modeling</h4></div><h4 class="hidden-sm hidden-xs">PredictionIO Docs</h4></div><div class="col-md-3 col-sm-1 col-xs-1 hidden-md hidden-lg"><img id="left-menu-indicator" src="/images/icons/down-arrow-dfe9f7fe.png"/></div><div class="col-md-3 col-sm-12 col-xs-12 swiftype-wrapper"><div class="swiftype"><form class="search-form"><img class="search-box-toggler hidden-xs hidden-sm" src="/images/icons/search-glass-704bd4ff.png"/><div class="search-box"><img src="/images/icons/search-glass-704bd4ff.png"/><input type="text" id="st-search-input" class="st-search-input" placeholder="Search Doc..."/></div><img class="swiftype-row-hider hidden-md hidden-lg" src="/images/icons/drawer-toggle-active-fcbef12a.png"/></form></div></div><div class="mobile-left-menu-toggler hidden-md hidden-lg"></div></div></div></div><div id="page" class="container-fluid"><div class="row"><div id="left-menu-wrapper" class="col-md-3"><nav id="nav-main"><ul><li class="level-1"><a class="expandible" href="/"><span>Apache PredictionIO® Documentation</span></a><ul><li class="level-2"><a class="final" href="/"><span>Welcome to Apache PredictionIO®</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Getting Started</span></a><ul><li class="level-2"><a class="final" href="/start/"><span>A Quick Intro</span></a></li><li class="level-2"><a class="final" href="/install/"><span>Installing Apache PredictionIO</span></a></li><li class="level-2"><a class="final" href="/start/download/"><span>Downloading an Engine Template</span></a></li><li class="level-2"><a class="final" href="/start/deploy/"><span>Deploying Your First Engine</span></a></li><li class="level-2"><a class="final" href="/start/customize/"><span>Customizing the Engine</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Integrating with Your App</span></a><ul><li class="level-2"><a class="final" href="/appintegration/"><span>App Integration Overview</span></a></li><li class="level-2"><a class="expandible" href="/sdk/"><span>List of SDKs</span></a><ul><li class="level-3"><a class="final" href="/sdk/java/"><span>Java & Android SDK</span></a></li><li class="level-3"><a class="final" href="/sdk/php/"><span>PHP SDK</span></a></li><li class="level-3"><a class="final" href="/sdk/python/"><span>Python SDK</span></a></li><li class="level-3"><a class="final" href="/sdk/ruby/"><span>Ruby SDK</span></a></li><li class="level-3"><a class="final" href="/community/projects/#sdks"><span>Community Powered SDKs</span></a></li></ul></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Deploying an Engine</span></a><ul><li class="level-2"><a class="final" href="/deploy/"><span>Deploying as a Web Service</span></a></li><li class="level-2"><a class="final" href="/batchpredict/"><span>Batch Predictions</span></a></li><li class="level-2"><a class="final" href="/deploy/monitoring/"><span>Monitoring Engine</span></a></li><li class="level-2"><a class="final" href="/deploy/engineparams/"><span>Setting Engine Parameters</span></a></li><li class="level-2"><a class="final" href="/deploy/enginevariants/"><span>Deploying Multiple Engine Variants</span></a></li><li class="level-2"><a class="final" href="/deploy/plugin/"><span>Engine Server Plugin</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Customizing an Engine</span></a><ul><li class="level-2"><a class="final" href="/customize/"><span>Learning DASE</span></a></li><li class="level-2"><a class="final" href="/customize/dase/"><span>Implement DASE</span></a></li><li class="level-2"><a class="final" href="/customize/troubleshooting/"><span>Troubleshooting Engine Development</span></a></li><li class="level-2"><a class="final" href="/api/current/#package"><span>Engine Scala APIs</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Collecting and Analyzing Data</span></a><ul><li class="level-2"><a class="final" href="/datacollection/"><span>Event Server Overview</span></a></li><li class="level-2"><a class="final" href="/datacollection/eventapi/"><span>Collecting Data with REST/SDKs</span></a></li><li class="level-2"><a class="final active" href="/datacollection/eventmodel/"><span>Events Modeling</span></a></li><li class="level-2"><a class="final" href="/datacollection/webhooks/"><span>Unifying Multichannel Data with Webhooks</span></a></li><li class="level-2"><a class="final" href="/datacollection/channel/"><span>Channel</span></a></li><li class="level-2"><a class="final" href="/datacollection/batchimport/"><span>Importing Data in Batch</span></a></li><li class="level-2"><a class="final" href="/datacollection/analytics/"><span>Using Analytics Tools</span></a></li><li class="level-2"><a class="final" href="/datacollection/plugin/"><span>Event Server Plugin</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Choosing an Algorithm</span></a><ul><li class="level-2"><a class="final" href="/algorithm/"><span>Built-in Algorithm Libraries</span></a></li><li class="level-2"><a class="final" href="/algorithm/switch/"><span>Switching to Another Algorithm</span></a></li><li class="level-2"><a class="final" href="/algorithm/multiple/"><span>Combining Multiple Algorithms</span></a></li><li class="level-2"><a class="final" href="/algorithm/custom/"><span>Adding Your Own Algorithms</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Tuning and Evaluation</span></a><ul><li class="level-2"><a class="final" href="/evaluation/"><span>Overview</span></a></li><li class="level-2"><a class="final" href="/evaluation/paramtuning/"><span>Hyperparameter Tuning</span></a></li><li class="level-2"><a class="final" href="/evaluation/evaluationdashboard/"><span>Evaluation Dashboard</span></a></li><li class="level-2"><a class="final" href="/evaluation/metricchoose/"><span>Choosing Evaluation Metrics</span></a></li><li class="level-2"><a class="final" href="/evaluation/metricbuild/"><span>Building Evaluation Metrics</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>System Architecture</span></a><ul><li class="level-2"><a class="final" href="/system/"><span>Architecture Overview</span></a></li><li class="level-2"><a class="final" href="/system/anotherdatastore/"><span>Using Another Data Store</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>PredictionIO® Official Templates</span></a><ul><li class="level-2"><a class="final" href="/templates/"><span>Intro</span></a></li><li class="level-2"><a class="expandible" href="#"><span>Recommendation</span></a><ul><li class="level-3"><a class="final" href="/templates/recommendation/quickstart/"><span>Quick Start</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/dase/"><span>DASE</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/evaluation/"><span>Evaluation Explained</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/how-to/"><span>How-To</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/reading-custom-events/"><span>Read Custom Events</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/customize-data-prep/"><span>Customize Data Preparator</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/customize-serving/"><span>Customize Serving</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/training-with-implicit-preference/"><span>Train with Implicit Preference</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/blacklist-items/"><span>Filter Recommended Items by Blacklist in Query</span></a></li><li class="level-3"><a class="final" href="/templates/recommendation/batch-evaluator/"><span>Batch Persistable Evaluator</span></a></li></ul></li><li class="level-2"><a class="expandible" href="#"><span>E-Commerce Recommendation</span></a><ul><li class="level-3"><a class="final" href="/templates/ecommercerecommendation/quickstart/"><span>Quick Start</span></a></li><li class="level-3"><a class="final" href="/templates/ecommercerecommendation/dase/"><span>DASE</span></a></li><li class="level-3"><a class="final" href="/templates/ecommercerecommendation/how-to/"><span>How-To</span></a></li><li class="level-3"><a class="final" href="/templates/ecommercerecommendation/train-with-rate-event/"><span>Train with Rate Event</span></a></li><li class="level-3"><a class="final" href="/templates/ecommercerecommendation/adjust-score/"><span>Adjust Score</span></a></li></ul></li><li class="level-2"><a class="expandible" href="#"><span>Similar Product</span></a><ul><li class="level-3"><a class="final" href="/templates/similarproduct/quickstart/"><span>Quick Start</span></a></li><li class="level-3"><a class="final" href="/templates/similarproduct/dase/"><span>DASE</span></a></li><li class="level-3"><a class="final" href="/templates/similarproduct/how-to/"><span>How-To</span></a></li><li class="level-3"><a class="final" href="/templates/similarproduct/multi-events-multi-algos/"><span>Multiple Events and Multiple Algorithms</span></a></li><li class="level-3"><a class="final" href="/templates/similarproduct/return-item-properties/"><span>Returns Item Properties</span></a></li><li class="level-3"><a class="final" href="/templates/similarproduct/train-with-rate-event/"><span>Train with Rate Event</span></a></li><li class="level-3"><a class="final" href="/templates/similarproduct/rid-user-set-event/"><span>Get Rid of Events for Users</span></a></li><li class="level-3"><a class="final" href="/templates/similarproduct/recommended-user/"><span>Recommend Users</span></a></li></ul></li><li class="level-2"><a class="expandible" href="#"><span>Classification</span></a><ul><li class="level-3"><a class="final" href="/templates/classification/quickstart/"><span>Quick Start</span></a></li><li class="level-3"><a class="final" href="/templates/classification/dase/"><span>DASE</span></a></li><li class="level-3"><a class="final" href="/templates/classification/how-to/"><span>How-To</span></a></li><li class="level-3"><a class="final" href="/templates/classification/add-algorithm/"><span>Use Alternative Algorithm</span></a></li><li class="level-3"><a class="final" href="/templates/classification/reading-custom-properties/"><span>Read Custom Properties</span></a></li></ul></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Engine Template Gallery</span></a><ul><li class="level-2"><a class="final" href="/gallery/template-gallery/"><span>Browse</span></a></li><li class="level-2"><a class="final" href="/community/submit-template/"><span>Submit your Engine as a Template</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Demo Tutorials</span></a><ul><li class="level-2"><a class="final" href="/community/projects/#demos"><span>Community Contributed Demo</span></a></li><li class="level-2"><a class="final" href="/demo/textclassification/"><span>Text Classification Engine Tutorial</span></a></li></ul></li><li class="level-1"><a class="expandible" href="/community/"><span>Getting Involved</span></a><ul><li class="level-2"><a class="final" href="/community/contribute-code/"><span>Contribute Code</span></a></li><li class="level-2"><a class="final" href="/community/contribute-documentation/"><span>Contribute Documentation</span></a></li><li class="level-2"><a class="final" href="/community/contribute-sdk/"><span>Contribute a SDK</span></a></li><li class="level-2"><a class="final" href="/community/contribute-webhook/"><span>Contribute a Webhook</span></a></li><li class="level-2"><a class="final" href="/community/projects/"><span>Community Projects</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Getting Help</span></a><ul><li class="level-2"><a class="final" href="/resources/faq/"><span>FAQs</span></a></li><li class="level-2"><a class="final" href="/support/"><span>Support</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Resources</span></a><ul><li class="level-2"><a class="final" href="/cli/"><span>Command-line Interface</span></a></li><li class="level-2"><a class="final" href="/resources/release/"><span>Release Cadence</span></a></li><li class="level-2"><a class="final" href="/resources/intellij/"><span>Developing Engines with IntelliJ IDEA</span></a></li><li class="level-2"><a class="final" href="/resources/upgrade/"><span>Upgrade Instructions</span></a></li><li class="level-2"><a class="final" href="/resources/glossary/"><span>Glossary</span></a></li></ul></li><li class="level-1"><a class="expandible" href="#"><span>Apache Software Foundation</span></a><ul><li class="level-2"><a class="final" href="https://www.apache.org/"><span>Apache Homepage</span></a></li><li class="level-2"><a class="final" href="https://www.apache.org/licenses/"><span>License</span></a></li><li class="level-2"><a class="final" href="https://www.apache.org/foundation/sponsorship.html"><span>Sponsorship</span></a></li><li class="level-2"><a class="final" href="https://www.apache.org/foundation/thanks.html"><span>Thanks</span></a></li><li class="level-2"><a class="final" href="https://www.apache.org/security/"><span>Security</span></a></li></ul></li></ul></nav></div><div class="col-md-9 col-sm-12"><div class="content-header hidden-md hidden-lg"><div id="breadcrumbs" class="hidden-sm hidden xs"><ul><li><a href="#">Collecting and Analyzing Data</a><span class="spacer">&gt;</span></li><li><span class="last">Events Modeling</span></li></ul></div><div id="page-title"><h1>Events Modeling</h1></div></div><div id="table-of-content-wrapper"><h5>On this page</h5><aside id="table-of-contents"><ul> <li> <a href="#1-generic-events-performed-by-an-entity">1. Generic events performed by an entity</a> </li> <li> <a href="#2-special-events-for-recording-changes-of-an-entity-s-properties">2. Special events for recording changes of an entity's properties</a> </li> <li> <a href="#3-batch-events-to-the-eventserver">3. Batch Events to the EventServer</a> </li> </ul> </aside><hr/><a id="edit-page-link" href="https://github.com/apache/predictionio/tree/livedoc/docs/manual/source/datacollection/eventmodel.html.md.erb"><img src="/images/icons/edit-pencil-d6c1bb3d.png"/>Edit this page</a></div><div class="content-header hidden-sm hidden-xs"><div id="breadcrumbs" class="hidden-sm hidden xs"><ul><li><a href="#">Collecting and Analyzing Data</a><span class="spacer">&gt;</span></li><li><span class="last">Events Modeling</span></li></ul></div><div id="page-title"><h1>Events Modeling</h1></div></div><div class="content"> <p>This section explains how to model your application data as events.</p><p><strong>Entity</strong>: it&#39;s the real world object involved in the events. The entity may perform the events, or interact with other entity (which became <code>targetEntity</code> in an event).</p><p>For example, your application may have users and some items which the user can interact with. Then you can model them as two entity types: <strong>user</strong> and <strong>item</strong> and the entityId can uniquely identify the entity within each entityType (e.g. user with ID 1, item with ID 1).</p><p>An entity may perform some events (e.g user 1 does something), and entity may have properties associated with it (e.g. user may have gender, age, email etc). Hence, <strong>events</strong> involve <strong>entities</strong> and there are three types of events, respectively:</p> <ol> <li>Generic events performed by an entity.</li> <li>Special events for recording changes of an entity&#39;s properties</li> <li>Batch events</li> </ol> <p>They are explained in details below.</p><h2 id='1.-generic-events-performed-by-an-entity' class='header-anchors'>1. Generic events performed by an entity</h2><p>Whenever the entity performs an action, you can describe such event as <code>entity &quot;verb&quot; targetEntity with &quot;some extra information&quot;</code>. The <em>&quot;targetEntity&quot;</em> and <em>&quot;some extra information&quot;</em> can be optional. The <em>&quot;verb&quot;</em> can be used as the name of the <em>&quot;event&quot;</em>. The <em>&quot;some extra information&quot;</em> can be recorded as <code>properties</code> of the event.</p><p>The following are some simple examples:</p> <ul> <li>user-1 signs-up</li> </ul> <div class="highlight json"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5</pre></td><td class="code"><pre><span class="p">{</span><span class="w">
  </span><span class="s2">"event"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"sign-up"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"entityType"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"user"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"entityId"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></pre></td></tr></tbody></table> </div> <ul> <li>user-1 views item-1 <em>(with targetEntity)</em></li> </ul> <div class="highlight json"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7</pre></td><td class="code"><pre><span class="p">{</span><span class="w">
  </span><span class="s2">"event"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"view"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"entityType"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"user"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"entityId"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"targetEntityType"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"item"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"targetEntityId"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></pre></td></tr></tbody></table> </div> <ul> <li>user-1 rates item-1 with rating of 4 stars <em>(with targetEntity and properties)</em></li> </ul> <div class="highlight json"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8
9
10</pre></td><td class="code"><pre><span class="p">{</span><span class="w">
  </span><span class="s2">"event"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"rate"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"entityType"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"user"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"entityId"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"targetEntityType"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"item"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"targetEntityId"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"properties"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="s2">"rating"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="mi">4</span><span class="w">
  </span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></pre></td></tr></tbody></table> </div> <h2 id='2.-special-events-for-recording-changes-of-an-entity&#39;s-properties' class='header-anchors'>2. Special events for recording changes of an entity&#39;s properties</h2><p>The generic events described above are used to record general actions performed by the entity. However, an entity may have properties (or attributes) associated with it. Moreover, the properties of the entity may change over time (for example, user may have new address, item may have new categories). In order to record such changes of an entity&#39;s properties. Special events <code>$set</code> , <code>$unset</code> and <code>$delete</code> are introduced.</p><p>The following special events are reserved for updating entities and their properties:</p> <ul> <li> <code>&quot;$set&quot;</code> event: Set properties of an entity (also implicitly create the entity). To change properties of entity, you simply set the corresponding properties with value again. The <code>$set</code> events should be created only when: <ul> <li> The entity is <em>first</em> created (or re-create after <code>$delete</code> event), or</li> <li> Set the entity&#39;s existing or new properties to new values (For example, user updates his email, user adds a phone number, item has a updated categories)</li> </ul></li> <li> <code>&quot;$unset&quot;</code> event: Unset properties of an entity. It means treating the specified properties as not existing anymore. Note that the field <code>properties</code> cannot be empty for <code>$unset</code> event.</li> <li> <code>&quot;$delete&quot;</code> event: delete the entity.</li> </ul> <p>There is no <code>targetEntityId</code> for these special events.</p><p>For example, setting entity <code>user-1</code>&#39;s properties <code>birthday</code> and <code>address</code>:</p><div class="highlight json"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8
9</pre></td><td class="code"><pre><span class="p">{</span><span class="w">
  </span><span class="s2">"event"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"$set"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"entityType"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"user"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"entityId"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1"</span><span class="p">,</span><span class="w">
  </span><span class="s2">"properties"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="p">{</span><span class="w">
    </span><span class="s2">"birthday"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1984-10-11"</span><span class="p">,</span><span class="w">
    </span><span class="s2">"address"</span><span class="w"> </span><span class="p">:</span><span class="w"> </span><span class="s2">"1234 Street, San Francisco, CA 94107"</span><span class="w">
  </span><span class="p">}</span><span class="w">
</span><span class="p">}</span><span class="w">
</span></pre></td></tr></tbody></table> </div> <p><strong>Note</strong> that the properties values of the entity will be aggregated based on these special events and the eventTime. The state of the entity is different depending on the time you are looking at the data. In engine&#39;s DataSource, you can use <a href="https://predictionio.apache.org/api/current/#org.apache.predictionio.data.store.PEventStore$">PEventStore.aggregateProperties() API</a> to retrieve the state of entity&#39;s properties (based on time).</p><div class="alert-message note"><p>Although it doesn&#39;t hurt to import duplicated special events for an entity (exactly same properties) into event server (it just means that the entity changes to the same state as before and new duplicated event provides no new information about the user), it could waste storage space.</p></div><p>To demonstrate the concept of these special events, we are going to import a sequence of events and see how it affects the retrieved entity&#39;s properties.</p><p>Assuming you have created the App (named &quot;MyTestApp&quot;) for testing and Event Server is started.</p><h4 id='event-1' class='header-anchors'>Event 1</h4><p>For example, on <code>2014-09-09T...</code>, a user with ID &quot;2&quot; is newly added in your application. Also, this user has properties a = 3 and b = 4. To record such event, we can create a <code>$set</code> event for the user.</p><p>for convenience, assign the ACCESS_KEY of your test app to the shell variable <code>ACCESS_KEY</code> and run following curl command to import the event:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8
9
10
11
12
13
14</pre></td><td class="code"><pre><span class="gp">$ </span><span class="nv">ACCESS_KEY</span><span class="o">=</span><span class="s2">"&lt;YOUR_ACCESS_KEY&gt;"</span>

<span class="gp">$ </span>curl -i -X POST http://localhost:7070/events.json?accessKey<span class="o">=</span><span class="nv">$ACCESS_KEY</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{
  "event" : "$set",
  "entityType" : "user",
  "entityId" : "2",
  "properties" : {
    "a" : 3,
    "b" : 4
  },
  "eventTime" : "2014-09-09T16:17:42.937-08:00"
}'</span>
</pre></td></tr></tbody></table> </div> <p>You should see something like the following, meaning the events are imported successfully.</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7</pre></td><td class="code"><pre>HTTP/1.1 201 Created
Server: akka-http/10.1.5
Date: Tue, 02 Jun 2015 23:13:58 GMT
Content-Type: application/json; <span class="nv">charset</span><span class="o">=</span>UTF-8
Content-Length: 57

<span class="o">{</span><span class="s2">"eventId"</span>:<span class="s2">"PVjOIP6AJ5PgsiGQW6pgswAAAUhc7EwZpCfSj5bS5yg"</span><span class="o">}</span>
</pre></td></tr></tbody></table> </div> <p>After this eventTime, user-2 is created and has properties of a = 3 and b = 4.</p><h4 id='event-2' class='header-anchors'>Event 2</h4><p>Then, on <code>2014-09-10T...</code>, let&#39;s say the user has updated the properties b = 5 and c = 6. To record such property change, create another <code>$set</code> event. Run the following command:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8
9
10
11
12</pre></td><td class="code"><pre><span class="gp">$ </span>curl -i -X POST http://localhost:7070/events.json?accessKey<span class="o">=</span><span class="nv">$ACCESS_KEY</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{
  "event" : "$set",
  "entityType" : "user",
  "entityId" : "2",
  "properties" : {
    "b" : 5,
    "c" : 6
  },
  "eventTime" : "2014-09-10T13:12:04.937-08:00"
}'</span>
</pre></td></tr></tbody></table> </div> <p>After this eventTime, user-2 has properties of a = 3, b = 5 and c = 6. Note that property <code>b</code> is updated with latest value.</p><h4 id='event-3' class='header-anchors'>Event 3</h4><p>Then, let&#39;s say on <code>2014-09-11T...</code>, the user&#39;s properties &#39;b&#39; is removed for some reasons. To record such event, create <code>$unset</code> event for user-2 with properties b:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8
9
10
11</pre></td><td class="code"><pre><span class="gp">$ </span>curl -i -X POST http://localhost:7070/events.json?accessKey<span class="o">=</span><span class="nv">$ACCESS_KEY</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{
  "event" : "$unset",
  "entityType" : "user",
  "entityId" : "2",
  "properties" : {
    "b" : null
  },
  "eventTime" : "2014-09-11T14:17:42.456-08:00"
}'</span>
</pre></td></tr></tbody></table> </div> <p>After this eventTime, user-2 has properties of a = 3, and c = 6. Note that property <code>b</code> is removed.</p><h4 id='event-4' class='header-anchors'>Event 4</h4><p>Then, on <code>2014-09-12T...</code>, the user is removed from the application data. To record such event, create <code>$delete</code> event:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8</pre></td><td class="code"><pre><span class="gp">$ </span>curl -i -X POST http://localhost:7070/events.json?accessKey<span class="o">=</span><span class="nv">$ACCESS_KEY</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{
  "event" : "$delete",
  "entityType" : "user",
  "entityId" : "2",
  "eventTime" : "2014-09-12T16:13:41.452-08:00"
}'</span>
</pre></td></tr></tbody></table> </div> <p>After this eventTime, user-2 is removed.</p><h4 id='event-5' class='header-anchors'>Event 5</h4><p>Then, on <code>2014-09-13T...</code>, let&#39;s say we want to add back the user-2 into the application again for some reasons. To record such event, create <code>$set</code> event for user-2 with empty properties:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8</pre></td><td class="code"><pre><span class="gp">$ </span>curl -i -X POST http://localhost:7070/events.json?accessKey<span class="o">=</span><span class="nv">$ACCESS_KEY</span> <span class="se">\</span>
-H <span class="s2">"Content-Type: application/json"</span> <span class="se">\</span>
-d <span class="s1">'{
  "event" : "$set",
  "entityType" : "user",
  "entityId" : "2",
  "eventTime" : "2014-09-13T16:17:42.143-08:00"
}'</span>
</pre></td></tr></tbody></table> </div> <p>After this eventTime, user-2 is created again with empty properties.</p><p>Note that all above events are recorded in Event Store. Let&#39;s query Event Server and see if these events are imported.</p><p>Go to following URL with your browser:</p><p><code>http://localhost:7070/events.json?accessKey=&lt;YOUR_ACCESS_KEY&gt;</code></p><p>or run the following command in terminal:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1</pre></td><td class="code"><pre><span class="gp">$ </span>curl -i -X GET <span class="s2">"http://localhost:7070/events.json?accessKey=</span><span class="nv">$ACCESS_KEY</span><span class="s2">"</span>
</pre></td></tr></tbody></table> </div> <div class="alert-message note"><p>Note that you should quote the entire URL by using single or double quotes when you run the curl command.</p></div><p>You should see all events being created for this user-2.</p><p>Now, let&#39;s retrieve the user-2&#39;s properties using the <a href="https://predictionio.apache.org/api/current/#org.apache.predictionio.data.store.PEventStore$">PEventStore API</a>.</p><p>First, start <code>pio-shell</code> by running:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1</pre></td><td class="code"><pre><span class="gp">$ </span>pio-shell --with-spark
</pre></td></tr></tbody></table> </div> <p>You should see the following output and shell prompt:</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6</pre></td><td class="code"><pre>15/06/02 16:01:54 INFO SparkILoop: Created spark context..
Spark context available as sc.
15/06/02 16:01:54 INFO SparkILoop: Created sql context <span class="o">(</span>with Hive support<span class="o">)</span>..
SQL context available as sqlContext.

scala&gt;
</pre></td></tr></tbody></table> </div> <p>Run the following code in PIO shell (Replace <code>&quot;MyTestApp&quot;</code> with your app name):</p><div class="highlight scala"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3</pre></td><td class="code"><pre><span class="n">scala</span><span class="o">&gt;</span> <span class="k">val</span> <span class="n">appName</span><span class="o">=</span><span class="s">"MyTestApp"</span>
<span class="n">scala</span><span class="o">&gt;</span> <span class="k">import</span> <span class="nn">org.apache.predictionio.data.store.PEventStore</span>
<span class="n">scala</span><span class="o">&gt;</span> <span class="nc">PEventStore</span><span class="o">.</span><span class="n">aggregateProperties</span><span class="o">(</span><span class="n">appName</span><span class="k">=</span><span class="n">appName</span><span class="o">,</span> <span class="n">entityType</span><span class="o">=</span><span class="s">"user"</span><span class="o">)(</span><span class="n">sc</span><span class="o">).</span><span class="n">collect</span><span class="o">()</span>
</pre></td></tr></tbody></table> </div> <p>This command is using PEventStore to aggregate the user properties as a Map of user Id and the PropertyMap. <code>collect()</code> will return the data as array. You should see the following output at the end, which indicates there is user id 2 with empty properties because that&#39;s the state of user 2 with all imported events taken into account.</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2</pre></td><td class="code"><pre>res0: Array[<span class="o">(</span>String, org.apache.predictionio.data.storage.PropertyMap<span class="o">)]</span> <span class="o">=</span>
Array<span class="o">((</span>2,PropertyMap<span class="o">(</span>Map<span class="o">()</span>, 2014-09-09T16:17:42.937-08:00, 2014-09-13T16:17:42.143-08:00<span class="o">)))</span>
</pre></td></tr></tbody></table> </div> <p>Let&#39;s say we want to retrieve the state of user 2 properties with only events 1 and event 2 imported. To do that, we can specify the untilTime (aggregate the user properties with events up to the specified time) in the API.</p><p>Run the following in the pio-shell. the untilTime is set to DateTime(2014, 9, 11, 0, 0) which is the time right before event 3.</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2</pre></td><td class="code"><pre><span class="gp">scala&gt; </span>import org.joda.time.DateTime
<span class="gp">scala&gt; </span>PEventStore.aggregateProperties<span class="o">(</span><span class="nv">appName</span><span class="o">=</span>appName, <span class="nv">entityType</span><span class="o">=</span><span class="s2">"user"</span>, <span class="nv">untilTime</span><span class="o">=</span>Some<span class="o">(</span>new DateTime<span class="o">(</span>2014, 9, 11, 0, 0<span class="o">)))(</span>sc<span class="o">)</span>.collect<span class="o">()</span>
</pre></td></tr></tbody></table> </div> <p>You should see the following ouptut and the aggregated properties matches what we expected as described earlier (right before event 3): user-2 has properties of a = 3, b = 5 and c = 6.</p><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2</pre></td><td class="code"><pre>res2: Array[<span class="o">(</span>String, org.apache.predictionio.data.storage.PropertyMap<span class="o">)]</span> <span class="o">=</span>
Array<span class="o">((</span>2,PropertyMap<span class="o">(</span>Map<span class="o">(</span>b -&gt; JInt<span class="o">(</span>5<span class="o">)</span>, a -&gt; JInt<span class="o">(</span>3<span class="o">)</span>, c -&gt; JInt<span class="o">(</span>6<span class="o">))</span>, 2014-09-09T16:17:42.937-08:00, 2014-09-10T13:12:04.937-08:00<span class="o">))</span>
</pre></td></tr></tbody></table> </div> <p>As you have seen in the example above, the state of user-2 is different depending on the available events or the time you are looking at the data. Recording events in logging fashioned allows us to re-construct the state the entity according to the time.</p><h2 id='3.-batch-events-to-the-eventserver' class='header-anchors'>3. Batch Events to the EventServer</h2><p>Using a different REST address on the usual EventServer port, as of PredictionIO 0.9.5 you can send batches of up to 50 events as a time. The format is as described above but the JSON payload is packaged as an array of Event objects.</p><p><strong>Response:</strong></p> <ul> <li>Status: <ul> <li>200 on success if we can return an array data in the response even when some events fail (e.g. because of ill-format). Client needs to check individual dictionary to verify all events were successfully created.</li> <li>400 otherwise. Perhaps exceeded 50 events?</li> </ul></li> <li>Data: an array of dictionaries each of which contains either following keys <ul> <li>“status”: 201 if the event was successfully created; otherwise, 400.</li> <li>&quot;eventID&quot;: the value is the eventID if the event is successfully created and</li> <li>&quot;message&quot;: the error message string if any error occurs during creation</li> </ul></li> </ul> <p>The order in the response array is corresponding to the order of the request array. However, the events might be imported in any order.</p><h3 id='sample-request:' class='header-anchors'>Sample Request:</h3><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24</pre></td><td class="code"><pre>curl -i -X POST http://localhost:7070/batch/events.json?accessKey<span class="o">=</span>...
-H <span class="s2">"Content-Type: application/json"</span> -d ‘ <span class="se">\</span>
<span class="o">[</span>
    <span class="o">{</span>
        <span class="s2">"event"</span>: <span class="s2">"</span><span class="nv">$create</span><span class="s2">"</span>,
        <span class="s2">"entityType"</span>: <span class="s2">"user"</span>,
        <span class="s2">"entityId"</span>: <span class="s2">"uid"</span>,
        <span class="s2">"properties"</span>: <span class="o">{</span>
            ...
        <span class="o">}</span>
    <span class="o">}</span>,
    <span class="o">{</span>
        <span class="s2">"event"</span>: <span class="s2">"like"</span>,
        <span class="s2">"entityType"</span>: <span class="s2">"user"</span>,
        <span class="s2">"entityId"</span>: <span class="s2">"uid"</span>,
        <span class="s2">"targetEntityType"</span>: <span class="s2">"item"</span>,
        <span class="s2">"targetEntityId"</span>: <span class="s2">"iid"</span>,
        <span class="s2">"properties"</span>: <span class="o">{</span>
            ...
        <span class="o">}</span>
        <span class="s2">"eventTime"</span>: <span class="s2">"2004-12-13T21:39:45.618-07:00"</span>
    <span class="o">}</span>,
    ...
<span class="o">]</span>‘
</pre></td></tr></tbody></table> </div> <h3 id='sample-response:' class='header-anchors'>Sample Response:</h3><div class="highlight shell"><table style="border-spacing: 0"><tbody><tr><td class="gutter gl" style="text-align: right"><pre class="lineno">1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22</pre></td><td class="code"><pre>HTTP/1.1 200 Successful
Server: akka-http/10.1.5
Date: Wed, 10 Sep 2014 22:51:33 GMT
Content-Type: application/json; <span class="nv">charset</span><span class="o">=</span>UTF-8
Content-Length: 41
<span class="o">[</span>
    <span class="o">{</span><span class="s2">"eventId"</span>:<span class="s2">"AAAABAAAAQDP3-jSlTMGVu0waj8"</span><span class="o">}</span>,
    <span class="o">{</span>
        <span class="s2">"status"</span>: 201,
        <span class="s2">"eventId"</span>: <span class="s2">"AAAABAAAAQDP3-jSlTMGVu0waj8"</span>
    <span class="o">}</span>,
    <span class="o">{</span>
        <span class="s2">"status"</span>: 201,
        <span class="s2">"eventId"</span>:<span class="s2">"AAAABAAAAQDP3-jSlTMGVu0waj9"</span>
    <span class="o">}</span>,
     …
    <span class="o">{</span>
        <span class="s2">"status"</span>: 400,
        <span class="s2">"message"</span>:<span class="s2">"Required entityType is missing”
    },
    …
]
</span></pre></td></tr></tbody></table> </div> <p>Notice that each subrequest receives a status response. The limit of 50 events per batch requests is in line with Facebook, Mixpanel, SegmentIO and other event syncs that accept batches.</p></div></div></div></div><footer><div class="container"><div class="seperator"></div><div class="row"><div class="col-md-6 footer-link-column"><div class="footer-link-column-row"><h4>Community</h4><ul><li><a href="//predictionio.apache.org/install/" target="blank">Download</a></li><li><a href="//predictionio.apache.org/" target="blank">Docs</a></li><li><a href="//github.com/apache/predictionio" target="blank">GitHub</a></li><li><a href="mailto:user-subscribe@predictionio.apache.org" target="blank">Subscribe to User Mailing List</a></li><li><a href="//stackoverflow.com/questions/tagged/predictionio" target="blank">Stackoverflow</a></li></ul></div></div><div class="col-md-6 footer-link-column"><div class="footer-link-column-row"><h4>Contribute</h4><ul><li><a href="//predictionio.apache.org/community/contribute-code/" target="blank">Contribute</a></li><li><a href="//github.com/apache/predictionio" target="blank">Source Code</a></li><li><a href="//issues.apache.org/jira/browse/PIO" target="blank">Bug Tracker</a></li><li><a href="mailto:dev-subscribe@predictionio.apache.org" target="blank">Subscribe to Development Mailing List</a></li></ul></div></div></div><div class="row"><div class="col-md-12 footer-link-column"><p>Apache PredictionIO, PredictionIO, Apache, the Apache feather logo, and the Apache PredictionIO project logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.</p><p>All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p></div></div></div><div id="footer-bottom"><div class="container"><div class="row"><div class="col-md-12"><div id="footer-logo-wrapper"><img alt="PredictionIO" src="/images/logos/logo-white-d1e9c6e6.png"/><span>®</span></div><div id="social-icons-wrapper"><a class="github-button" href="https://github.com/apache/predictionio" data-icon="octicon-star" data-show-count="true" aria-label="Star apache/predictionio on GitHub">Star</a> <a class="github-button" href="https://github.com/apache/predictionio/fork" data-icon="octicon-repo-forked" data-show-count="true" aria-label="Fork apache/predictionio on GitHub">Fork</a> <script id="github-bjs" async="" defer="" src="https://buttons.github.io/buttons.js"></script><a href="https://twitter.com/predictionio" target="blank"><img alt="PredictionIO on Twitter" src="/images/icons/twitter-ea9dc152.png"/></a> <a href="https://www.facebook.com/predictionio" target="blank"><img alt="PredictionIO on Facebook" src="/images/icons/facebook-5c57939c.png"/></a> </div></div></div></div></div></footer></div><script>(function(w,d,t,u,n,s,e){w['SwiftypeObject']=n;w[n]=w[n]||function(){
(w[n].q=w[n].q||[]).push(arguments);};s=d.createElement(t);
e=d.getElementsByTagName(t)[0];s.async=1;s.src=u;e.parentNode.insertBefore(s,e);
})(window,document,'script','//s.swiftypecdn.com/install/v1/st.js','_st');

_st('install','HaUfpXXV87xoB_zzCQ45');</script><script src="/javascripts/application-d943a254.js"></script></body></html>