Persistent Derived Tables (PDTs) are an important Looker feature that enable complex analysis within Looker. Looker displays several admin features that can help track and troubleshoot PDT behavior on the Persistent Derived Tables page, which admins and users with the appropriate permissions can access from the Database section of Looker’s Admin panel.
The Persistent Derived Tables page displays information about PDTs, such as the PDT name, the build status, the LookML models it is included in, its persistence type, the time of the last successful build, and options for viewing additional details.
The Persistent Derived Tables page shows only the connections that have PDTs enabled and only the PDTs that meet the following criteria:
- The PDT is defined in a view file that is in production.
- The PDT is part of a model that is correctly configured.
- The PDT is part of a model for which you have data access.
Information on this page is based on an internal PDT event log, described in the PDT Event Log Model section below.
Understanding the PDT Page
The Persistent Derived Tables page lists all PDTs for the connection selected in the connection selector. The selector shows only connections that have PDTs enabled and to which users have data access.
Click the downward arrow next to the connection name to view the PDTs of a different connection or select All Connections to view a consolidated list of all PDTs for connections to which you have data access on that Looker instance:
All Connections is the default option in the connection selector. A status message below the selector indicates the progress of the PDTs loading for each connection that has PDTs enabled. Click the Show newly loaded PDTs link to display the results for PDTs that have fully loaded while all PDTs are being retrieved.
By default, the Persistent Derived Tables page displays 25 PDTs on a single page. To view additional PDTs, you can:
- Click the arrows at the bottom of the page to navigate to the next or previous page.
- Click the display selector to increase the number of results displayed on a single page.
PDT Name
The PDT Name column displays the name of the PDT as defined in the view
parameter of the PDT’s LookML view file.
A column subheading indicates if the row is displaying information about an old PDT build. See the PDT Details pop-up in the Options menu for more information about this message.
Last Build Status
The Last Build Status column displays the current build status of each listed PDT:
- regenerating indicates that the PDT can be queried, and there is an updated table currently building.
- success indicates that a PDT has successfully built.
- building indicates that a PDT is currently building and cannot be queried until the build is completed.
- not built indicates that a PDT is not currently built.
- failed indicates that an error has occurred during a build. You can click Build Error to see the error’s source and navigate to the PDT’s LookML if you have the appropriate permissions to see LookML. See the Options section to learn more about troubleshooting PDTs from the Persistent Derived Tables page.
Last Successful Build
The Last Successful Build column indicates the time that has elapsed since the last successful PDT build.
Last Build Duration
The Last Build Duration column displays the amount of time in seconds that it took for the latest build of that PDT and how long it takes to build the PDT on average in seconds.
Persistence Rule
The Persistence Rule column displays the type of persistence applied to a PDT, as defined in the PDT’s view file. It also indicates the last time a successfully built PDT was checked (for trigger type PDTs) or when a successfully built PDT is due to expire (for persist type PDTs). There are two types of persistence displayed in the Persistence Rule column:
- Persist is displayed for PDTs that are persisted with the
persist_for
parameter. - Trigger is displayed for PDTs that are persisted with either a
datagroup_trigger
or asql_trigger_value
parameter. You can click the trigger type to view the trigger’s SQL statement. For datagroup triggers, this is thesql_trigger
subparameter value for thedatagroup
parameter. For SQL triggers, this is thesql_trigger_value
value.
Connection
If All Connections is selected from the connection select, the Connection column appears and displays the name of the connection on which the PDT is enabled.
Model
The Model column displays the name of the model file in which the PDT’s view file is included.
If a PDT view file is included in multiple model files that share the same connection, multiple models will appear in the Model column. If a PDT view file is included in multiple model files with different connections, the PDT will also appear in other connection PDT lists.
It is important to be explicit when including view files in models, as including all view files may clutter your database schema and cause multiple copies of PDTs to build on your database, or on multiple databases.
Options
The three-dot Options menu is especially useful for troubleshooting unexpected behavior. You can check when tables were last built, check how long they took to build, compare the latest build time against the average build time, and check whether triggers are working correctly. The three-dot menu displays a list of more options, including:
- Go to LookML — Opens the view file in which the PDT is defined if you have the appropriate permissions to see LookML.
- Recent Build Events — Opens the PDT event log to a pre-built Explore showing all recent build events for a specific PDT.
- Recent Trigger Events — Opens the PDT event log to a pre-built Explore showing all trigger events for a specific PDT.
- PDT Details — Opens a pop-up containing more information and statistics for a specific PDT:
- Table Name: The hash of the latest successfully built PDT.
- Model: The name of the model file in which the PDT’s view file is included
- Stable Name: If the PDT has been published as a stable view, as determined by its
publish_as_db_view
parameter value, the name of the stable database view. - Connection: The name of the connection on which the PDT is enabled.
- Old Build: A Boolean that indicates if a build was (if Yes) or was not (if No) an old PDT build.
- Table Type: For old builds, indicates the table type. Values include Old Generation Table and Standin.
- Status: Gives the Last Build Status. For failed builds, provides SQL error message and a link to the model’s LookML if the user has the appropriate permissions to see LookML.
- Build Info
- Latest Build Duration: How long the most recent PDT build took (in seconds; N/A if the table has not yet been built).
- Avg Build Duration: How long it takes to build the PDT on average (in seconds; N/A if the table has not yet been built).
- Build Reason: The reason a PDT was built (inception for an initial build, datagroup triggered if the PDT is persisted with a datagroup, trigger value change if the PDT’s SQL trigger value changed).
- Persistence Rule
- Type: The value from the Persistence Rule column.
- Persist For: For Persist type PDTs, the persistence duration value. Not applicable for Trigger type PDTs.
- Datagroup: For Trigger type PDTs, the trigger’s SQL statement; for datagroup triggers, this is the
sql_trigger
subparameter value for thedatagroup
parameter. - Trigger Value: For Trigger type PDTs, the value that triggered the PDT build (N/A for successfully built PDTs persisted with a
datagroup_trigger
; to see the most recent trigger value for a datagroup, see the Datagroups page in the Admin panel). - Last Checked: For Trigger type PDTs, when the trigger value was last checked.
- Expires: When the PDT expires, if applicable (not applicable for datagroup triggers).
See the Help Center article Troubleshooting PDT Regeneration for more troubleshooting tips.
Searching, Sorting, and Filtering the PDT Page
You can refine the PDT list by using the search bar and filters menu in the top right of the Persistent Derived Tables page — even use the search bar and filters in conjunction for more precise searching. You can also sort your results by specific columns.
Searching
You can use the search bar in the upper right corner of the Persistent Derived Tables page to narrow the PDT list. Type a word in the search bar to limit the Persistent Derived Tables page display by PDTs that contain that word, or search for a specific PDT by name. The results will show PDTs with the matching search term in bold.
The example below is a search for PDTs that contain the word orders:
Click the X in the search bar to clear your search query terms. You may need to refresh the Persistent Derived Tables page to see the full list of PDTs.
Sorting
Click the heading names for PDT Name, Last Build Status, or Last Successful Build, Last Build Duration, or Connection to sort the list of PDTs by any of those columns.
Sorting by the PDT Name, Last Build Status, or Connection (if All Connections is selected in the connection selector) column will arrange the list of PDTs in alphabetical or reverse alphabetical order by name, build status, or connection, respectively.
Sorting by the Last Successful Build column will arrange the list of PDTs in chronological order from most recent build or least recent build.
Filtering
You can use the Filter icon next to the search bar to choose which PDTs are shown on the Persistent Derived Tables page. For example, you can filter by Last Build Status to view only the PDTs that are experiencing a build error, or you can filter by Model to limit the PDTs shown to a specific model.
To filter the Persistent Derived Tables page:
- Click the Filters icon.
- Select a filter option from the first filter selector in the filter menu. Options include:
- Not Triggered in the Last — Filters the Persistent Derived Tables page by PDTs that have not been triggered in a specified number of hours and minutes.
- Triggered in the Last — Filters the Persistent Derived Tables page by PDTs that have been triggered within a specified number of minutes.
- Model — Filters the Persistent Derived Tables page for PDTs included in a specified model.
- PDT Type — Filters the Persistent Derived Tables page by PDT persistence type.
- Status — Filters the Persistent Derived Tables page by a specified PDT status.
- Published as Stable View — A Boolean that filters the Persistent Derived Tables page for PDTs that were (Yes) or were not (No) published as a stable view, as determined by their
publish_as_db_view
parameter value. - Last Build Duration Longer Than — Filters the Persistent Derived Tables page by PDTs whose builds took longer than a specified number of seconds.
- Choose the value on which you want to filter the Persistent Derived Tables page in the second filter selector. In the case of the Not Triggered Since Minutes or Triggered Since options, enter a number of hours or minutes. In the case of the Last Build Duration Longer Than option, enter a number of seconds.
- Click Add Filter to add more filters, and repeat steps 2 and 3 for each filter you are adding.
- If at any point you wish to clear your filter selections and start over, click Clear All. To remove any individual additional filters, click Clear above the filter you wish to remove.
- Click Apply to apply the selected filter criteria to the Persistent Derived Tables page.
You will see the applied filters at the top of the Persistent Derived Tables page:
Click the X next to an applied filter to remove it from the Persistent Derived Tables page. Click Clear All to clear all filters.
PDT Event Log Model
Looker includes a pre-built model named system_activity
to allow easy exploration of the PDT event log. The PDT event log is a table in a database connection’s temp schema that tracks the trigger and build activity of PDTs. In addition to Recent Build Events and Recent Trigger Events links in the Options three-dot menu of the Persistent Derived Tables page, the model also can be accessed from the Connections page in the Looker Admin panel. To access the PDT event log Explore from the Connections page, select the Show PDT Event Log option from the gear menu drop-down to the far right of each connection:
You can explore the model as with any other Looker Explore. When accessed from the Connections page, the PDT Event Log Explore will be filtered for the entire connection. When accessed from the Persistent Derived Tables page, the PDT Event Log Explore will be filtered for a specific PDT.
This is a brief guide to the fields that are available:
Field | Description |
---|---|
Action | Describes the action that occurred; this may include regeneration, drop, creation, and reaping activity. |
Action Data | Provides more specific detail about an action, including the trigger being used, the value of a trigger, the expiration time for a persistent table, the cause of a rebuild, the text of an error message, and so on. |
Connection | The name of the connection that the derived table exists on. |
Hash | Each derived table contains a hash of the SQL that was written to create it. |
ID | The unique ID of the Looker instance that generated the PDT. In many cases, there will be only one Looker instance pointing at a database, so you will only see a single ID. However, if you have a staging instance, or something of that nature, you may see multiple IDs. |
Model Name | The name of the model through which the table was generated. |
Occur Date | The date and time the event occurred. |
Occur Utc Display Date | The date and time the event occurred in UTC. |
Sequence | A step number in the PDT build. |
Short Hash | A truncated version of the hash of the SQL that was written to create the derived table. |
Table Name | The full name of the PDT, including the table-type prefix, a hash, and the view name. |
Tid | The transaction ID. |
View Name | The view name for the derived table. |