Skip to main content


Scuba Docs

Using a 2.x per-actor metric as a 3.x actor property

Per-actor metrics in 2.x are very similar to Actor properties in 3.x. However, actor properties currently do not support the "activity" aggregation option.


This article shows you how to create a per-actor metric in Scuba 2.x, and then an actor property in Scuba 3.x. We use the movies database in both examples.

Create and use a 2.x per-actor metric

Per-actor metrics calculate how many times an event occurs during a specified period of time, such as the number of users active out of a 7 day period. Scuba displays per-actor metrics as metric <metric name> in lists. You can create queries to measure metrics that analyze the characteristics of different actors, or filter to compare subsets of actors based on ad-hoc criteria.

In the following example, we create a per-actor metric for Movies watched for each user in dataset movies.

To create a 2.x per-actor metric, do the following:
  1. In Explorer, select the Metrics icon in the left navigation bar.


  1. Click New Metric in the upper right corner of the window. The New Metric dialog appears.


  1. Enter a Name and select a Dataset from the drop-down menu. In our example, we named the metric Movies watched and selected the movies dataset.
  2. Select a For each option and Measure from the drop-down menus. In our example, we selected (For each) user and Count Events as the measure.
  3. For Filter, click Basic and specify filter options in each of the fields. In our example, we selected action as the first filter option, followed by is one of and watch_movie.
  4. Enter a Description for the metric, and click Save. A table list of metrics appears.


  1. Click the Explore icon to the right of the metric you just created. The Explorer window appears using the metric in the query builder on the left.
  2. Specify a Start and End time, and then click GO. You can select from the calendar, or enter a value. We entered a Start time of 200 days ago, and an End time of now.


Queries are run as Sampled by default. 

  1. To view unsampled results, under Chart Controls, deselect the Sampled Query radio button so the check mark disappears, then click Apply.


We received the following unsampled results for our example query.


To use the 2.x per-actor metric in a query, do the following:
  1. Click inside the View field and select Time from the drop-down menu. The results will be displayed over time.


  1. Keep the Start time of 200 days ago, and End time now.
  2. Select a Measure from the drop-down list. We selected Sum for our example.
  3. Enter or select the name of a metric in the field below. We entered the Movies watched.
  4. For Groups, select user from the drop-down list. This will show a time line for each user.
  5. Select Chart Controls and make sure the Sampled Query radio button is not checked.
  6. Click GO. and uncheck All others in the legend beneath Time view. We received the following results for our example.


Create and use a 3.x actor property

An actor is the "who or what" that is performing an event. An actor can be a user, physical object (such as a device), digital object (like a subreddit), or a bot.

Actor columns are identified at ingest time by explicitly making them shard keys. When an event source has multiple actor populations, they are implemented through multiple shard keys on the same dataset (table). An actor is one of the “mandatory” fields for every logged event, which also includes a timestamp and name of the event.

This section demonstrates how to create an actor property. In our example, we create an actor property that determines the movies watched by each user over a specified time.

To create a 3.x actor property, do the following:
  1. In the left navigation bar, click Actors.
  2. In the top right corner of the window, click New Actor Property.


  1. Choose a dataset from the drop-down list at the top of the window. In this example, we chose the movies dataset.


  1. At the top of the page, enter a unique name for the actor property. We named our property Movies watched in the last 200 days.


  1. Select an actor from the drop-down list. In this example, we selected user. Your options reflect your data.


  1. Next to Method, make sure that Show is selected.
  2. On the next line, choose the appropriate options from the drop-down lists. In our example data, we chose count of events.
  3. Make selections for Filtered to options. We chose events with action that matches watch_movie.


  1. Click the Time range radio button (for more information, see specify relative time in a query) and specify Starting time and Ending time values. We entered a Starting time of 200 days ago and an Ending time of now for our example.
  2. Click Save.
To use the 3.x actor property in a query, do the following:
  1. Select the Explore icon in the left navigation bar, and select the database from the drop-down list. We selected the movies database.
  2. Select Show count of events in the first line of the query builder.
  3. For Filtered to, we selected the actor property Movies watched in the last 200 days. The sentence model query builder automatically fills in text and provides a greater than option. We accepted the default of is greater than 0.


  1. Choose to Split by user actor. This will show movies watched results by user.
  2. Specify a Starting and Ending time. We entered a Starting time of 200 days ago and an Ending time of now.


  1. Toggle to ALL for an unsampled query, then click GO.


  1. In the legend on the right, select All others and toggle to Hide Line. This normalizes the results by hiding an outlier.


We received the following results for our example.



  • Was this article helpful?