Message path syntax

Message path syntax is used throughout Studio to help you drill down to the exact information you want to inspect in your data.

Topics and fields

Reference this sample message for the /my_models topic:

{
  total: 4,
  objects: [
    { width: 10, height: 20 },
    { width: 15, height: 30 },
    { width: 20, height: 40 },
    { width: 25, height: 50 }
  ]
}

Specify the topic name to display all messages for that topic:

/my_models =>
  {
    total: 4,
    objects: [
      { width: 10, height: 20 },
      { width: 15, height: 30 },
      { width: 20, height: 40 },
      { width: 25, height: 50 }
    ]
  }

To access nested fields, first specify the topic, then use dot notation to drill down into a nested field:

/my_models.total => 4

Typing any text into a message path input field will display a list of matching autocomplete options – any topics or nested fields that contain the user-input text will be included in this list.

Index into an array with bracket notation:

/my_models.objects[1].width => 15
/my_models.objects[-1].width => 25

Slices

Reference this sample message for the /my_options topic:

{
  colors: [
    { r: 10, g: 20, b: 100 },
    { r: 15, g: 30, b: 50 },
    { r: 20, g: 40, b: 20 },
    { r: 25, g: 50, b: 70 },
    { r: 30, g: 60, b: 90 },
  ],
  numbers: [3, 5, 7, 9, 10]
}

Slices will return an array of values:

/my_options.colors[1:2] => [{ r: 15, g: 30, b: 50 }, { r: 20, g: 40, b: 20 }]
/my_options.numbers[-2:-1] => [9, 10]

Using dot notation after an array of objects will map through to access each element's nested field:

/my_options.colors[1:3].r => [15, 20, 25]
/my_options.colors[:].g => [20, 30, 40, 50, 60]

Slice on a variable by prepending each variable name with a $. For example, if you've set $my_start_idx to 3 and $my_end_idx to 4:

/my_options.colors[$my_start_idx:$my_end_idx] => [{ r: 25, g: 50, b: 70 }, { r: 30, g: 60, b: 90 }]
/my_options.colors[$my_start_idx:$my_end_idx].b => [70, 90]

/my_options.numbers[$my_start_idx:$my_end_idx] => [9, 10]

Filters

Reference these sample messages for the /my_books topic:

// message 1
{
  stats: {
    pages: 100,
    author: "Beatrice Potter"
  },
  readers: [
    { id: 1, name: "Ashley", isCurrentlyReading: true },
    { id: 2, name: "Baron", isCurrentlyReading: false },
    { id: 3, name: "Charlie", isCurrentlyReading: true }
  ]
}

// message 2
{
  stats: {
    pages: 210,
    author: 'Tommy "Two Gun" Simon'
  },
  readers: [
    { id: 4, name: "Dana", isCurrentlyReading: true },
    { id: 5, name: "Ethan", isCurrentlyReading: false },
    { id: 6, name: "Frank", isCurrentlyReading: false }
  ]
}

Filter messages based on their fields’ boolean, number, or string values. Only equality is currently supported.

Filter on top-level fields using curly brackets – messages that don't match the filter will be skipped entirely:

/my_books{stats.pages==210} =>
  {
    stats: {
      pages: 210,
      author: 'Tommy "Two Gun" Simon'
    }
  }

/my_books{stats.pages==100}.author => "Beatrice Potter"

/my_books{stats.pages==500} => // no value returned

You can also filter on a message’s nested field values using a combination of slices and filters:

/my_books.readers[:]{isCurrentlyReading==true}.name =>
  ["Ashley", "Charlie"] // message 1
  ["Dana"] // message 2

In addition to filtering on primitive values, you can filter on a variable:

/my_books.readers[:]{id==$my_id} =>
  { id: 1, name: "Ashley", isCurrentlyReading: true } // message 1
  // No value returned for message 2

When you apply multiple filters, only messages that satisfy all filters will be returned (i.e. an AND expression):

/my_books.readers[:]{id==1}{isCurrentlyReading==true}.name =>
  "Ashley" // message 1
  // No value returned for message 2

/my_books.readers[:]{id==1}{isCurrentlyReading==false}.name =>
  // No value returned for message 1
  // No value returned for message 2

/my_books.readers[:]{id==5}{isCurrentlyReading==false}.name =>
  // No value returned for message 1
  "Ethan" // message 2

We don't support escaping quotation marks in strings, but you can use single or double quotes, which allows you to express most strings

/my_books{stats.author=='Tommy "Two Gun" Simon'}.readers[:].name =>

  // No value returned for message 1
  ["Dana", "Ethan", "Frank"] // message 2