Skip to main content

User Guide

Screen Layout​

TimeBase Web Admin application screen is divided into two sections: a list of streams and the main screen.

TimeBase records time-series data in streams. See Basic Concepts for details. Vertical panel on the left displays all streams and spaces available in your specific TimeBase instance in a lexicographic order. You can expand each stream by selecting the up or down carrot to view stream instruments (symbols). A context menu is available using your right mouse button and actions vary deepening on whether a stream name or an instrument is highlighted. Here you can also find a Views tab with pinned data queries.

All the stream data, charts, and other information is displayed on the main screen to the right of the list of streams.

Create Stream​

You can create new stream right from the TimeBase Web Admin application.

  1. Click Create new stream in the toolbar.
  2. Enter Stream Key in the dialog window and click Start Creating to open a stream schema editor.

TimeBase is designed to work with records of different types, we call them messages. In object-oriented programing languages messages can be seen as classes, each with a specific set of fields. Messages are arranged chronologically in streams.

Each stream has a unique stream schema, which declares what types of messages (including their hierarchy) a specific stream may store. This differs TimeBase from traditional relational databases with flat structure. Uniqueness of stream schema means, that identical classes defined by different stream schemas are in fact independent classes and are not treated as identical on a TimeBase level. Stream schema may as well include applicable enumerations.

Practical Example​

For demonstration purposes lets take a MyBarMessage class from deltix.samples.timebase.basics sample package. In this example we will create a new stream with a sample class, create loader to write some demo data into the stream and view recorded data in Web Admin application.

  1. Click Create new stream in the toolbar.
  2. Enter Demo Stream Key in the dialog window and click Start Creating to open a stream schema editor.
  3. Click New Class in the schema editor and create MyBarMessage class.
  4. Add new fields:
  • closePrice, NON STATIC FLOAT IEEE64
  • openPrice, NON STATIC FLOAT IEEE64
  • highPrice, NON STATIC FLOAT IEEE64
  • lowPrice, NON STATIC FLOAT IEEE64
  • volume, NON STATIC FLOAT IEEE64
  • exchange, NON STATIC CHAR
  1. Create a Loader to write data into a sample stream. Make sure to use your new stream name.
  2. Click View to see recorded messages.

You can also add messages manually. Refer to Send Message to learn more. Refer to client's APIs samples for more information.

Import/Export​

You can find EXPORT TO JSON and IMPORT FROM JSON buttons in the stream schema editor screen when you start creating a new stream schema or edit an existing stream schema.

  • EXPORT TO JSON - you can export a schema of any existing stream to a JSON file.
  • IMPORT FROM JSON - you can use a JSON file with a pre-configured schema to create new stream/edit existing stream schema. In case it is applied to the existing stream, new schema from a JSON file will override the existing stream schema. The original stream schema will be restored if there are any errors in the JSON file.
tip

Make sure the JSON file you import is valid; otherwise, it will be rejected with an error. To pass the validation, a JSON file must include a state key with arrays of classes and enums. Each array must include objects with name, title, and fields array. In the fields array there must be objects with name, title, and type. In case a JSON file is missing any of those, it will be rejected with a corresponding error message.

A JSON file must be also valid from the business logic perspective, for example, it must have a valid hierarchy of classes. Always make sure your file is up to date with the most recent system updates.

You will get a JSON parse error when importing a not valid JSON or another file format.

Revert​

You can find REVERT button in the fields editor screen when you start creating a new stream or open an existing stream schema.

REVERT works per field. Use it to undo all the unsaved changes made to a specific class field. REVERT is disabled in case no changes have been made to a selected field.

Stream Actions​

Right-click any stream or use a menu icon next to it to display available actions in the context menu.

View​

Select View to look at stream data. Click the Properties icon to view the stream's properties. While viewing the data within the main screen, you can double click any record to open details.

Refer to Dashboard for more information on the actions available in the View dashboard.

Reverse View​

Select Reverse View to display all the stream's data starting with the latest timestamp at the top of the screen.

Monitor​

Use monitor mode to view latest records for each symbol in the selected stream in real-time.

Inspector​

Use inspector mode to view updates for the latest 100 records in the selected stream in real time. The latest messages are displayed on top of the list.

Chart​

Click Chart and select a trading instrument to display charts for.

Schema​

Click Schema to display stream schema details. You can also edit, import, and export stream schema. Refer to Create Stream to learn more.

Query​

Use Query to run data queries. In the query area of the screen you will have a pre-populated query to get all messages from the corresponding stream.

Example
SELECT * FROM "KRAKEN"
info
  • Refer to Queries for more information about working with queries in this application.
  • Refer to QQL Tutorials for more information about the TimeBase Query Language.

Truncate​

Truncating a stream will remove all data after a specified time.

  1. Highlight a stream, right-click to open a context menu, select Truncate.
  2. Select all or individual symbols that you wish to be truncated.
  3. The stream's time range will be displayed in the time slider. You can either use the slider to specify the truncate to time or you can define the time and date within the Date input area.
  4. Specify a Time Zone and select OK.
  5. Select OK for confirmation.

Purge​

Purging a stream removes all data that is older than a specified start date.

  1. Highlight a stream, right-click to open a context menu, select Purge.
  2. The stream's time range will be displayed in the time slider.
  3. You can either use the slider to specify the purge from time or you can define the time and date within the Date input area.
  4. Specify a Time Zone and select OK.
  5. Select OK for confirmation.
tip

The purge process can be aborted but it will not return to its initial state.All data that was removed prior to aborting the process will be lost.

Delete Stream​

Use Delete to remove a specific stream from the system.

  1. Highlight a stream, right-click to open a context menu, select Delete.
  2. Click Delete in the dialog window to confirm or Cancel to abort

Change name​

Use Change Name to rename a specific stream.

  1. Highlight a stream, right-click to open a context menu, select Change name.
  2. Enter a new name in the text area and click Rename to confirm

Describe​

Use Describe to display a QQL code with stream schema description. You can use this as a template to create new streams or modify existing streams.

tip

Refer to General Controls to learn more.

Send Message​

Use this to manually add new messages to the selected stream. Stream schema determines what classes of messages can be recorded to a specific stream. Each message class has an individual set of fields. See Basic Concepts for more information.

  1. Highlight a stream, right-click to open a context menu, select Send message.
  2. Specify parameters values using either the UI or in a JSON format.
  3. Select one of the writing modes. Append is the default writing mode.
  4. Click Revert to clear all entries.
  5. Click Send to submit a new message to a stream.
tip

Note, that available parameters are determined by the message class and may vary significantly for messages of different classes.

Export to QMSG​

You can export the entire stream data, including all stream messages, to a file of a proprietary QSMG format. You can use this file to easily import stream data to another TimeBase instance.

Export to CSV​

You can export the entire stream data, including all stream messages, to a CSV file.

In the Export to CSV from you can specify what exactly you would like to export

  • Set the data time range.
  • Select ALL symbols or specify symbols to be exported.
  • Browse through stream schema classes and fields and select which ones you wish to export.
  • Select the output CSV file configurations.

Import​

Click Import to import a new stream into the system in a QSMSG file format.

Symbol Actions​

Unfold any stream to view symbols and right-click any symbol to display available actions in the context menu:

View​

Click View to look at a selected symbol's data. Double click any record in the main monitoring screen to open details.

info

Refer to Dashboard for more information on action available in the View dashboard.

Reverse View​

Select Reverse View to look at a selected symbol's data starting with the latest timestamp at the top of the screen.

Monitor​

Monitor allows viewing real-time updates for a specific symbol. Double click any record in the main monitoring screen to open details.

Inspector​

Use inspector to view updates for the latest 100 records for the selected symbol in real-time. The latest messages are displayed on top of the list.

Chart​

Charts show the incoming market data and help verify that the market data aggregator is consuming and storing data properly. TimeBase Web Administrator charts are not designed to be used as a financial research tool.

info

Charts can display data for a single contract per panel.

The No chart data message notifies the user that charting is not supported for a particular selection.

The user will receive a warning in case the data within the selected stream is not capable of being charted and the chart function is selected.

  • Time range - use the time picker drop-down to select one of the preset time intervals or set a custom time range in the calendar. Click-and-drag chart to move along the timeline, you can also use left/right arrow controls on your keyboard to do the same. Use a mouse scroll to zoom-in and zoom-out in time.
  • Track - click Track to view chart in real-time.
  • View data - on any type of charts, right-click on the chart and select View data to open a View mode for the selected instrument.
  • Exchanges - in case your stream includes market data from more than one exchange, a drop down list in the right-hand corner will allow selecting all or any specific exchange to display on the chart.

Price Chart​

Select Prices_L2 type to view Level2 market data for the selected instrument. Use Levels drop-down to choose how many levels to display on each side of the market.

Trades BBO​

Select Trades_BBO to view Level1 data and trades.

Bar Chart​

You can use several types of Bar Charts depending on the price type:

  • Mid-Price
  • Ask
  • Bid

The size of bars can be modified using the Bar size drop-down.

Linear Chart​

You can display time-series data for numeric fields in messages in a Line chart.

Click Gear icon in the left-hand pane to display Linear chart settings. In Chart Settings you can enable/disable any attribute displayed on the chart.

Order Book​

You can right-click any symbol in the stream and select Order Book. This way you display a pre-configured order book for a selected stream and symbol. Still, you can add more streams and exchanges to display an aggregated order book.

Query​

Click Query to open a window where you can run QQL queries. In the query area of the screen you will have a pre-populated query to get all messages with the selected symbol from the corresponding stream.

Example
SELECT * FROM "KRAKEN" WHERE symbol == 'BTC/USD'
info
  • Refer to Queries for more information about working with queries in this application.
  • Refer to QQL Tutorials for more information about the TimeBase Query Language.

Change Name​

Use Change Name to rename a specific symbol.

  1. Highlight a symbol, right-click to open a context menu, select Change name.
  2. Enter a new name in the text area and click Rename to confirm.

Export to QMSG​

You can export data for the selected symbol to a file of a proprietary QSMG format.

Export to CSV​

You can export data for the selected symbol to a CSV file.

In the Export to CSV from you can specify what exactly you would like to export

  • Set the data time range.
  • Select ALL symbols or specify symbols to be exported.
  • Browse through stream schema classes and fields and select which ones you wish to export.
  • Select the output CSV file configurations.

Materialized Views​

Overview​

In general terms, a materialized view is an objects that contains the result of a QQL query. In TimeBase, we call it a View. The basic principle is that you can extract data via a QQL query from one stream and save it in a dedicated stream, which will get updated along with the data in the source stream.

You can use Views to have custom data selections or data transformations from TimeBase streams. By creating a View, you basically pre-process your query once and use it afterwards as a ready dataset, which may significantly reduce the processing time, unlike running the same query over and over again every time you need it.

As a result, you can keep your data extract in a dedicated stream and work with it the same way you work with any other TimeBase stream in a Web Admin application or via API, for example draw charts - refer to examples.

Design Principles​

Lifecycle​

Views acquire different states throughout their lifecycle.

StateDescription
CREATEDA newly-created stream acquires this state.
PROCESSINGThis state indicates that the query is currently under processing by the server. On the UI, it is indicated by the loading icon next to the name of the View.
IDLEA View acquires this state when not in PROCESSING and is waiting for updates in the source stream.
FAILEDA View acquires this state in case of an error in the source stream or any other error while processing the QQL query.
COMPLETEDA View that does not draw data from a stream acquires this state once the QQL query is finalized.
REMOVEDDeleted Views acquire this state.

Data Handling​

Views operate in a so-called live mode when they query data from TimeBase streams. In this case, new data (QQL query output) is added to the target stream of the View with every new message that comes to the source stream. Naming for target streams follows this pattern: "VIEW_NAME#view#".

info

A View gets restarted and the target stream is rewritten completely every time a source stream is truncated or its schema changes.

When a View does not draw data from any stream, we say that it is not operating in a live mode. Its QQL query is processed once, the results are written into the target stream, and the View acquires a COMPLETED state.

There is a system stream views#, not available on the UI but accessible via TimeBase API, where all metadata, states, errors, QQL query and other information about each View is recorded.

Processing Views​

You can configure the server to assign dedicated threads to process Views. Workers that process Views are evenly distributed among all the assigned threads.

There are two ways to configure dedicated threads to process Views:

  • Add JAVA system property: -Dviews.processor.thread-pool-size=8

  • Configure the application.yaml:

    views:
      processor: 
        thread-pool-size: 8 # default is 4
info

The default value: 4

Workers that process Views take up processing resources on your machine, they open cursors and loaders, create streams and record data. This gets even more important when it comes to Views operating in a live mode.

tip

The number of active views directly affects the performance of the entire application so please keep this in mind when working with them.

Working with Views​

All your Views are located in the same screen area as streams in a dedicated tab. Following the stream management pattern, you can perform a number of actions on your Views, which you can access from the context menu of each View - as shown on the screenshot. Refer to stream actions and symbol actions to learn more about the available actions.

Create​

There are two ways to create Views:

Delete​

You can delete any of your Views by clicking Delete View in the context menu of the selected View.

View Details​

You can access some of the View details from the side menu:

Click to open a View Properties screen with the basic View details such as stream name, state, last timestamp and a QQL query.
Click to open a Description of the View screen. On this screen, you can switch between the QQL query and a View stream schema description, which you can copy and use to create other streams.

Examples​

Views represent data extracted via a QQL query from other TimeBase streams. In this section, we will show how to do that on a several examples.

Bars​

In this example, we will create a View with price bars based on L2 data from COINBASE.

  1. Click Query Mode to open a new tab where you can run QQL queries.

  2. In our example, we will create a View for an extract from the COINBASE stream. Run the following QQL query to select price data from bar messages for BTC/USD: 

    WITH entries[this is TradeEntry] as 'entries'
    SELECT 
    first{}(entries[0].price) as 'open',
    last{}(entries[-1].price) as 'close',
    max{}(max(entries.price)) as 'high',
    min{}(min(entries.price)) as 'low'
    TYPE "deltix.timebase.api.messages.BarMessage"
    FROM "COINBASE" 
    OVER TIME(1m)
    WHERE symbol == 'BTC/USD' AND notEmpty(entries)

  3. Click Create View to create a new materialized view. Lets name it COINBASE_BARS for example purposes.

  4. Switch to Views tab and type in COINBASE in the search box to locate your new View. Click it to display data.

  5. You can click d in the side menu to view the details. There, we can see the QQL query we used to create this View.

  6. We can visualize the data aggregated by our View in a bar chart. To do that, click Chart in the context menu.

Indicators​

In this example, we will create a View with financial indicators based on L2 data from COINBASE exchange.

  1. Click Query Mode to open a new tab where you can run QQL queries.

  2. In our example, we will create a View for an extract from the COINBASE stream. Run the following QQL query to calculate various financial indicators for BTC/USD: 

    WITH entries[this is TradeEntry] as 'entries',
    sum(entries.price * entries.size) / sum(entries.size) as 'avgPrice',
    bollinger{}(avgPrice) as 'bollinger'
    SELECT
    avgPrice,
    sma{timePeriod: 1h}(avgPrice) as 'sma-1h',
    cma{}(avgPrice) as 'cma',
    ema{period: 14}(avgPrice) as 'ema-14',
    bollinger.upperBand,
    bollinger.middleBand,
    bollinger.lowerBand
    FROM coinbase
    OVER TIME(1m)
    WHERE symbol == 'BTC/USD' AND notEmpty(entries)

  3. Click Create View to create a new materialized view. Lets name it COINBASE_IND for example purposes.

  4. Switch to Views tab and type in COINBASE in the search box to locate your new View. Click it to display data.

  5. You can click d in the side menu to view the details. There, we can see the QQL query we used to create this View.

  6. We can visualize the data aggregated by our View in a line chart. To do that, click Chart in the context menu.

General Controls​

Toolbar​

Use a toolbar to quickly access:

Views​

In the Views tab you can find all you QQL queries saved as Views. Similar to streams and symbols, you can right-click any View or click the menu icon to open available actions.

Create View​

You can create a new view by clicking + and selecting Create view.

Then, type in your QQL query and give your View a name. After that, you can access this View from the Views tab.

tip

Refer to Views to learn more about materialized views in TimeBase.

Order Book​

Order Book is an aggregation of market data from one or across several exchanges for a selected trading instrument. TimeBase Web Admin allows you to view also a Market Depth Chart on the same screen, that gives a quick glimpse into supply (Ask) and demand (Bid) on the market, by showing the available to buy/sell volumes at/above/below each price level.

There are several ways to display order book:

Toolbar​

Click Order Book icon on the toolbar. You will view a blank order book page where you need to populate some data to display order book:

  1. Select at least one stream.
  2. Pick a Symbol (trading instrument) you want to display the order book for.
  3. In the Exchanges filter you can enable exchanges you want to build order book for.

Symbol Actions​

You can right-click any symbol in the stream and select Order Book. This way you display a pre-configured order book for a selected stream and symbol. Still, you can add more streams and exchanges to display an aggregated order book.

Stream Message Details​

tip

Order Book is available only in View/Reverse View Symbol View modes. In these modes you can only display a static view of the order book, unlike two previous options.

  1. Right-click any symbol in the stream and select View/Reverse View.
  2. In the main monitoring screen, right-click any message and select View Order Book to open Stream Message Details in the Order Book view mode.

Search box is located at the top of the streams list and allows to quickly locate stream(s)/symbols available in your specific TimeBase instance.

Available Search Options

  • Use wildcards - search by typing in a java-style wildcard.
  • Use regular expressions - search by java-supported regular expression.
  • Match exactly - search by the exact input value.
  • Match any - search any occurrences of the input value.
  • Default option: "Match any".
tip

"Use wildcards" and "Use regular expressions" are self-excluding options. Use either or approach.

"Match exactly" and "Match any" are self-excluding options. Use either or approach.

Screen Controls​

  • Click the Collapse/Expand icon next to the TimeBase title to show/hide the streams list.
  • Click the Down Arrow icon to expand/collapse symbols in a specific stream.
  • Click Collapse All to quickly collapse all the expanded streams.
  • Hover over any stream and click the Open in new tab to open stream data in a new tab.

Queries​

TimeBase Web Admin application allows querying streams' data using a TimeBase proprietary data query language called QQL. You can invoke a Query window from the Toolbar, Stream, and Symbol actions menus.

You can open more than one Query tab at the same time and run different queries with different settings in each of them. As you type in your query text, query editor offers autocomplete options and formatting hints (click Ctrl + Space anywhere in the query line to show available options). You may double click any field in the query output area to view stream details in a JSON format.

Query Modes​

  • Run - run QQL query.
  • Live - subscription to the latest data starting from the query timestamp.
  • Monitor - look at your query execution in real-time.

Recent Queries​

Recent Queries dropdown allows you to quickly access all the queries that you have recently created.

Export​

You can export your query results to CSV or QSMSG format.

Create View​

You can create a View based on your QQL query.

  1. Enter a QQL query in the text area.

  2. Click Create View, give it a Name and click Create.

  3. You can now access you View in the Views tab.

tip

Refer to Views to learn more about materialized views in TimeBase.

Share Query​

Click to generate a URL to share your current query.

Errors​

In case of an error, the corresponding query elements are highlighted in red right in the query text and user receives an error message. You can use Cancel to stop any running query in case it takes an excessive time to process it by the back-end.

tip

Refer to QQL Tutorials for more information about QQL and all the supported features.

Stream, Message, and Symbol Details​

In the main monitoring area you can preview stream, message, and symbol properties. Please note, that you cannot display both at the same time. Selecting one disables the other.

Display Message Details​

  1. Select any stream to view stream data in the main monitoring area.
  2. Double-click any message in the selected stream to show Stream Message Details in the additional window.
  3. You can switch between VIEW, JSON, and ORDER BOOK view modes.
  • In VIEW mode you can view general information about the selected message.
  • In JSON mode you can view classes and fields of the selected message in a JSON format.
  • In ORDER BOOK mode you can view the order book for the selected instrument and exchange at a particular time.
tip

You can also click m icon in the right-hand pane to display message details.

Display Stream Properties​

Select any stream and click information icon (highlighted on the screenshot) to view it's properties.

Display Stream Description​

From stream, symbol or chart view you can click d in the right-hand pane to display the current stream schema.

Display Symbol Properties​

Having selected a specific symbol in a stream, you may click information icon (highlighted on the screenshot) to view the selected symbol's properties. Same applies within charts.

Working With Dashboard​

  • Use the column context menu to:
    • Pin, Unpin, or Reset Grid to default state.
    • Autosize All or a Specific column to the default size.
    • Choose columns to be displayed in the grid.
  • Use grid context menu to
    • Copy a specific field in JSON format.
    • Export to CSV, MS Excel, XML.
    • Send Message
  • Additional information is available for selected grid fields when double clicking a row (e.g. Entries)
  • Use mouse scroll to move up and down the displayed time range.
  • Use Time bar to navigate within the entire available time range.
  • Click Export to export the selected data.

Working With Tabs​

When Open in a new tab checkbox is enabled in the Stream List, each new selection will be displayed within a separate tab within the main window.

All open tabs are displayed in the top pane of the main window.

Use Tabs List located next to the Settings in the upper-right corner to:

  • View all open tabs.
  • Navigate between tabs.
  • Close all open tabs at once .

Working With Filter​

Select the Filter button to filter out stream data:

  • Filter by Symbol
  • Filter by Message Type

Working With Time Box​

Use the Time Box input field and/or calendar icon to set the displayed Start From date.

  • Use Apply to apply selection .
  • Use Clean to reset the selection to the initial state.

Settings​

  • Tabs List - use to view, navigate, and hide open tabs.
  • Stream's Properties - click to display Properties window for a particular stream.
  • Use Global Settings to set:
    • Date Format.
    • Time Format.
    • Time Zone (local time zone is detected and populated automatically).
  • Check Show spaces to display spaces in the streams list.