Hello,
I was tasked with incorporating geospatial time series data into our application and found the existing documentation somewhat sparse. Knowing that we’ll have to do this multiple times in the future, I created this document to record what I went through to save future time for myself or the next engineer. I am sharing it here to “give back” the community.
ALL DATA SHOWN HERE IS FAKE/SYNTHETIC AND FOR DEMONSTRATION PURPOSES ONLY
@palantir: Feel free to incorporate any of this info into the official docs
Summary
This is a tutorial on how to setup a geospatial time series in Palantir Foundry. It will go through the raw data, ingestion, ontology setup and UI layers. Current Palantir docs have this information spread around or not at all.
The current architecture we will used is represented by this Palantir image:
To use our Entity
object as an example (and throughout this document), we have a backing dataset that contains entity information, one row per entity. Now we want to track Entity location data.
Entity has a geohash
property that represents its latest location but we also want location data (expressed via longitude and latitude decimal values) as a series of updates. That will come in as a separate dataset.
We will take these two datasets and merge them into a single Ontology Object Type that contains entity information and location information.
The ontology object will hold the entity object and a reference to the latitude and longitude series ids that will be used to lookup the series data in a separate dataset.
Palantir Documentation
Time Series Overview
Time Series Setup
Map Documentation:
Visualizing Tracks
Setting up Tracks
Pipeline Builder
Time Series Data
Our raw will start off as a csv table with ids, timestamps and telemetry:
entity_id,timestamp,longitude,latitude
526113ab-1716-4576-93dd-b95b48f0ea94,2025-01-01 08:00:00,139.7492435017863,35.760715052555454
526113ab-1716-4576-93dd-b95b48f0ea94,2025-01-01 14:00:00,140.00967739239792,35.26515165956454
526113ab-1716-4576-93dd-b95b48f0ea94,2025-01-01 20:00:00,139.59324468994296,35.72314690453366
457bb4d4-7f47-4543-aed4-9970e16d747a,2025-01-02 08:00:00,135.7608724786598,35.122287181255686
457bb4d4-7f47-4543-aed4-9970e16d747a,2025-01-02 14:00:00,136.23092720463333,34.676058547493064
457bb4d4-7f47-4543-aed4-9970e16d747a,2025-01-02 20:00:00,135.9048716137617,34.8603307654945
We then need to massage the data in order to create Series Ids (as explained above):
In the Pipeline Builder, add this data and perform the following actions:
- Unpivot the raw data to create a separate row for each telemetry data update
- Concatenate the
Entity Id
andSeries Name
to create aSeries Id
- Drop the unnecessary columns
Here is what the pipeline pseudo code looks like:
Output this to a dataset and this gets us our time series-based data set:
series_id,series_value,timestamp
latitude_457bb4d4-7f47-4543-aed4-9970e16d747a,34.291030087959484,2025-01-01T08:00:00Z
latitude_457bb4d4-7f47-4543-aed4-9970e16d747a,34.622537798173965,2025-01-01T14:00:00Z
latitude_526113ab-1716-4576-93dd-b95b48f0ea94,35.760715052555454,2025-01-01T08:00:00Z
latitude_526113ab-1716-4576-93dd-b95b48f0ea94,35.26515165956454,2025-01-01T14:00:00Z
longitude_457bb4d4-7f47-4543-aed4-9970e16d747a,135.71396623734535,2025-01-01T08:00:00Z
longitude_457bb4d4-7f47-4543-aed4-9970e16d747a,135.76183677192864,2025-01-01T14:00:00Z
longitude_526113ab-1716-4576-93dd-b95b48f0ea94,139.7492435017863,2025-01-01T08:00:00Z
longitude_526113ab-1716-4576-93dd-b95b48f0ea94,140.00967739239792,2025-01-01T14:00:00Z
Object Data
We now need to update the backing dataset to include references to Series IDs
. We do this by concatenating the Entity with the static string of the series name:
The preview should look like:
Ontology
Now that we have our prepared datasets, we can make the necessary Ontology Edits to combine the data.
In your Ontology:
- Add two properties to your Object,
Latitude Series
andLongitude Series
- Set the
Base Type
toTime Series
- When you create the first property, a popup will come up asking you to setup the time series. Select
Set Up Later
- Under
Source
, make sure thatDataSource
is selected and select the appropriateBacking Column
It should look like this, including the preview of the data including the series id columns
Now switch to Capabilities
from the left panel and:
- Navigate to
Base Types
>Time Series
>Time Series Properties
and selectAdd Property
- Select
Latitude Series
from before as yourObject Type Property
- Select the
Time Series-Basted Data Set
that was an output fromPipeline Builder
above - Set the
Series ID
,Value
, andTime
columns appropriately - Select
Add property
- Foundry will automatically create the Time Series Sync dataset
- Repeat steps 2-5 for
Longitude Series
and select the Time Series Sync dataset that was created for the first property.
It should look like this when you are done:
Once that’s done its time to move downward (on the same Capabilities sub-page) to the Geospatial
section. Set the Track Latitude
and Track Longitude
properties to their respective columns.
Save
these Ontology changes.
UI
As a quick sanity check, once your ontology changes are done indexing, you should be able to view a record in the Object Explorer
and see the time series data.
To demo these data changes, navigate to your project folder and add a new Map and :
-
Under
Layers
, selectAdd to Map
and select your Ontology Object andAdd
your desired objects. -
Your objects (with geospatial data) should have appeared showing its tracks. If not, press
Ctrl+A
and select a record that has geospatial data. -
Under
Layers
>Entities
, you might need to set theTrack
property underGeometry
-
Select a record with Geospatial data and go to the
Series
tab. The two series should be there. Click the...
(appears on hover) to the right of the series name and selectOpen in Series View
. Do that for both properties -
In the Series View, I like to
Group by Object
and change theTime
so that it focuses on the relevant time window (it seems to default to show 4 years).
-
You can click, hold, and move your mouse around in the Series View to “watch” the object move around
-
It should look like this:
-
Feel free to play around with the multitude of styling options available within the Map.
-
Don’t forget to
Save
the Map!
And that’s it!
P.S. If anyone runs through this and finds any gaps, feel free to let me know!