home User Guide Getting Started Help Center Documentation Community Training Certification
menu
close
settings
Looker keyboard_arrow_down
language keyboard_arrow_down
English
Français
Deutsch
日本語
search
print
Customizing Looker Marketplace Blocks

Looker Blocks™ are pre-built data models for common analytical patterns and data sources. This page describes how developers can customize Looker Blocks™ installed from the Looker Marketplace. The Looker Marketplace is a central location for finding, deploying, and managing many types of Looker content such as applications, visualizations, and plug-ins.

Blocks whose projects involve extends are installed from the Marketplace as a read-only CORE project and an editable CONFIG project. Blocks that are based on projects that use refinements are installed from the Marketplace as a single, editable LookML project that remotely imports the project containing all LookML code and constant parameterization.

For more information about all available Looker Blocks, including blocks that are not currently available from the Looker Marketplace, as well as alternate block customization methods, see the Looker Blocks documentation page.

add

Starting in June 2021, Looker Blocks that are available from the Looker Marketplace for instances on Looker 21.8 or later are being converted to a new structure that utilizes LookML refinements rather than extends.

Requirements for installing Looker Blocks from the Looker Marketplace

Before you can install and use some blocks from the Looker Marketplace, your Looker admin must enable these features:

Users must have develop, manage_models, and deploy permissions to install packages from the Marketplace.

See the Looker Marketplace documentation page for information on installing and managing Looker Blocks from the Looker Marketplace.

Marketplace Blocks that use refinements

Blocks that are based on projects that use refinements are installed from the Marketplace as a single, editable CONFIG project that remotely imports the CORE project, which contains all LookML code and constant parameterization.

Accessing the LookML for a refinements block

Once a block is installed from the Marketplace, you can access its project from the Develop menu by clicking the name of the project in the project list. The name of a Marketplace refinements block is typically prepended with marketplace_ followed by the listing ID.

Although you cannot directly modify a block’s read-only CORE project, you may want to use the LookML that is defined in the block’s read-only CORE files as a reference when you customize the block’s CONFIG files. You can see the block’s CORE files by navigating to the block’s project files in the IDE and expanding the imported_projects directory in the IDE file browser:

Block file structure

When you install a block that is built for refinements, these files are created automatically as part of the CONFIG part of the block project:

Filename Access Function
<model_name>.model.lkml Read-only for all users Virtual model file that is tied to the block installation; handles the import of any models from the block’s CORE project. When a block is uninstalled or updated, the associated model file or files are deleted, preventing model conflicts between multiple block installations.
manifest.lkml Editable for users with develop permissions Describes the project and its external dependencies. Contains the Marketplace listing ID for the block installation and facilitates the remote import of the block’s CORE project files through the marketplace keyword.
marketplace_lock.lkml Read-only for all users Contains a reference to the marketplace_ref keyword from the manifest file that handles the remote import of the CORE project. Provides the specific listing, version, and model information that is associated with the installation. Contains information about constants that are configured during installation (and that can be updated by using the Manage option in the Marketplace UI).
refinements.lkml Editable for users with develop permissions Allows developers to refine views and Explores defined in the imported CORE project files.

Customizing a block that uses refinements

Enable Development Mode to make customizations to the block’s editable files.

If you have develop permissions, you can customize the LookML in the refinements.lkml file of the block’s CONFIG project. You can refine the views and Explores that are already defined in the block’s CORE project or even add new views and Explores that aren’t already defined in the CORE project. Anything that is possible with LookML refinements in other LookML projects is possible in the block’s refinements.lkml file. The combination of the refinement and the original LookML behaves as if it is the original LookML for the object.

You can also make changes to the CONFIG project’s manifest.lkml file to specify any dependencies that need to be captured for that block.

You are not limited to modifying these files to attain the customizations you want. You can also create new files in the CONFIG project — just be sure to include any new files in the refinements.lkml file.

Customizing the refinements file

If you have develop permissions, you can add custom LookML to the CONFIG project to mix in additional data or change the core analytical model of the block. You can create new views and join them to existing Explores, define new fields or redefine existing fields, or apply labels as needed to create a model for the analysis you want to provide. If you’ve created new files in the CONFIG project, you must include them in the refinements file.

For example, say you’ve installed a block and its refinements.lkml file contains:

include: "//<listing_id>//*.view.lkml" include: "//<listing_id>//*.explore.lkml"

where listing_id is the value of the listing parameter from the manifest.lkml file.

You can use refinements to add a new dimension to a view called flights:

include: "//<listing_id>//*.view.lkml" include: "//<listing_id>//*.explore.lkml" view: +flights { dimension: air_carrier { type: string sql: ${TABLE}.air_carrier ;; } }

Or you can apply a label to an Explore called aircraft so that it appears in the UI as Aircraft Simplified:

include: "//<listing_id>//*.view.lkml" include: "//<listing_id>//*.explore.lkml" explore: +aircraft { label: "Aircraft Simplified" }

The refinements.lkml file is included automatically in the block’s “virtual” model file, which essentially imports the models from the CORE project.

See the LookML refinements documentation for more information about this advanced topic.

Customizing the editable manifest file

In blocks that use refinements, both the CORE and CONFIG projects have manifest files; however, only the CONFIG project’s manifest file is editable.

You can edit the CONFIG manifest.lkml file to add project parameters to those that already appear in the CORE project’s manifest file. For example, you can add a local_dependency to join your block to another block on the same Looker instance.

Before you can use or build on a block that contains a local_dependency parameter, a Looker admin must first enable the Local Project Import Labs feature.

Updating values for constants

The block’s constants are defined in the imported CORE project’s manifest file. Overriding a constant’s value, if allowed, must be done in the Marketplace UI during configuration or by updating the block. To update a block, users must have develop, manage_models, and deploy permissions.

To override a constant’s value by updating a block:

  1. In the Looker Marketplace, navigate to the block that you want to update.
  2. Click the Manage button.
  3. Next to the name of the block you want to update, click the gear icon. This opens the block configuration window.
  4. Make changes to the constant values as needed.
  5. Click Update to close the block configuration window and update the block with your changes.

Your changes are reflected in the read-only marketplace_lock.lkml file in your installed project.

Customizing a Marketplace Block that extends LookML objects

Before you can use or build on a block that contains a local_dependency parameter, a Looker admin must first enable the Local Project Import Labs feature.

Each block consists of a read-only CORE project and an editable CONFIG project.

Developers can customize a block by editing the files in the block’s CONFIG project. For example, you can create or modify dimensions and measures, define new views and join them to Explores, and make changes to existing Explores and dashboards. The changes you make in the CONFIG project will be brought into the CORE project’s content layer — the content that users interact with in Looker — and reflected in the block’s Explores and dashboards.

Accessing the LookML for a block

In addition to the method described in this section, you can also use LookML refinements to build on the LookML of views and Explores in your projects.

Once a block is installed from the Marketplace, you can access its CONFIG project from the Develop menu, by clicking either (A) Manage LookML Projects or (B) the name of a CONFIG project in the projects list. CONFIG projects typically end in _config, whereas the name of the CORE project typically does not have a suffix.

Although you cannot directly modify a block’s read-only CORE project, you may want to use the LookML that is defined in the block’s read-only CORE project as a reference when you customize the block’s CONFIG project. To view the block’s CORE project:

  1. From the Develop menu, select Manage LookML Projects.

  2. On the LookML Projects page, beneath the Marketplace Projects heading, (A) click the name of the project or (B) slick the View LookML button to the right of the CORE project’s listing.

Defining and redefining fields

You can add custom LookML to the CONFIG project to mix in additional data or change the core analytical model of the block. You can create new views and join them to existing Explores as needed to create a model for the analysis you want to provide.

You can define new fields or redefine existing fields by modifying the views in the CONFIG project. For example, suppose you want to create a new measure that evaluates whether the total sale price for an order is greater than $1,000. In this example, there is a measure total_sale_price defined in the orders_core view in the CORE project:

measure: total_sale_price { type: sum value_format_name: usd sql: ${sale_price} ;; drill_fields: [detail*] }

In the orders_config view in the CONFIG project, you can define a measure of type: yesno called is_large_total. In this example, the sql parameter evaluates whether the total_sale_price value is greater than $1,000.

measure: is_large_total { description: "Is order total over $1000?" type: yesno sql: ${total_sale_price} > 1000 ;; }

As another example, suppose you want to hide a dimension called customer_email from the field picker. To do this, you can set customer_email to hidden: yes in the orders_config view:

view: orders_config { extends: [orders_core] extension: required dimension: customer_email { hidden: yes } }

Joining views to existing Explores

In a block’s CONFIG project, you can create new views and join them to the block’s existing Explores, or you can join existing views to the block’s Explores.

For example, suppose you have created a new view in the CONFIG project, customer_address, that you would like to join to the Orders Explore. You can join the new customer_address view to the orders_config Explore in the CONFIG project as follows:

explore: orders_config { join: customer_address { sql_on: ${customer_address.customer_id} = ${orders_config.customer_id} ;; type: left_outer relationship: many_to_one } }

Because the orders Explore in the CORE project extends the orders_config Explore, the new customer view will be joined to and available to query in the Orders Explore.

Customizing Explores

In addition to joining new views to a block’s existing Explores, you can make further customizations, such as changing the label for the Explore, or specifying whether the Explore should be hidden from the Explore menu.

For example, suppose you have a Customers Explore that you want to hide from the Explore menu. In the block’s CORE project, there are two Explores defined, customers_core and customers. The Customers Explore in the UI is based on the customers Explore, which extends customers_config:

explore: customers_core { extension: required } explore: customers { extends: [customers_config] }

Because the customers Explore extends the customers_config Explore, changing the customers_config Explore in the CONFIG project to hidden: yes also sets customers to hidden: yes and hides the Customers Explore from the Explore menu:

explore: customers_config { extends: [customers_core] extension: required hidden: yes }

Customizing dashboards

You can create new dashboards or make changes to a block’s existing dashboards, such as by adding new tiles or changing a dashboard’s layout. You can customize an existing dashboard by making a user-defined dashboard (UDD) or LookML copy of the dashboard and editing the copy.

You can make a copy of the dashboard by first converting it to a user-defined dashboard. Or, you can navigate to the dashboard file in the CORE project and copy its contents, then create a new dashboard file.

To make changes to a dashboard using a UDD copy:

  1. Navigate to the dashboard.
  2. From the gear menu, select Copy from LookML into a folder.
  3. In the Copy Dashboard window, choose a folder and select Copy or Copy & View to create a UDD copy of the dashboard.
  4. Make the desired changes to the UDD copy of the dashboard.

  5. Once you have finished editing the dashboard, select Get LookML from the dashboard’s three-dot menu and then navigate to the Dashboard tab. For legacy dashboards, select Get Dashboard LookML from the dashboard’s gear menu.

  6. In the Dashboard LookML window, select Copy to Clipboard to copy the dashboard LookML.

  7. Create a new dashboard file in the CONFIG project, and paste the copied LookML from your clipboard into the file.
  8. In the new dashboard file, use the extends parameter to extend the original dashboard.
  9. Save the new LookML dashboard file.

To make changes to a dashboard using a LookML copy:

  1. Navigate to the dashboard file in the CORE project and copy the LookML for the desired dashboard.
  2. In the CONFIG project, create a new dashboard file and paste the LookML that you copied from the CORE project.
  3. In the new dashboard file, use the extends parameter to extend the original dashboard.
  4. Make any desired changes to the dashboard LookML.

Because the CONFIG project’s LookML dashboard files are included in the CORE project, dashboards you add to the CONFIG project will be listed with the block’s other dashboards and Explores.

Overriding extended LookML with sql_table_name

You can override LookML that is extended into the CONFIG project from the CORE project, such as the schema or table name that is provided in the sql_table_name parameter for a view.

In this example, the view issue_core is written as follows in the read-only CORE project for a block:

include: "//@{CONFIG_PROJECT_NAME}/github.view" view: issue { extends: [issue_config] } view: issue_core { sql_table_name: @{GITHUB_SCHEMA}.issue ;; … }

Let’s suppose that github_skeleton is the value provided for the GITHUB_SCHEMA constant, which is defined in the CORE project’s manifest file as follows:

constant: GITHUB_SCHEMA { value: "github_skeleton" export: override_required }

Before making any changes to the above LookML, we can see that the SQL for a query that uses an Explore based on the issue table is written as follows:

SELECT CASE WHEN issue.pull_request THEN 'Yes' ELSE 'No' END AS issue_pull_request, COUNT(*) AS issue_count FROM github_skeleton.issue AS issue GROUP BY 1 ORDER BY 2 DESC LIMIT 500

In the issue_config view in the CONFIG project, you can specify a different schema and table name for the view by using the sql_table_name parameter. This will override the values defined in the CORE project.

view: issue_config { extension: required extends: [issue_core] sql_table_name: github_dev.issue_dev ;; }

In this example, the schema github_skeleton is replaced with the schema github_dev, and the table name issue is replaced with the value issue_dev. After this change is saved, the SQL from the same Explore as above adjusts to the new values for sql_table_name:

SELECT CASE WHEN issue.pull_request THEN 'Yes' ELSE 'No' END AS issue_pull_request, COUNT(*) AS issue_count FROM github_dev.issue_dev AS issue GROUP BY 1 ORDER BY 2 DESC LIMIT 500

Troubleshooting a block

If a Marketplace Block displays errors, it’s possible that your schema doesn’t match the structure of the block.

You may also want to check that the constants that were provided during the block’s installation, representing the block’s connection, database, or schema, have been defined correctly. To do this, you can:

  1. Navigate to the Looker Marketplace by selecting the shop icon ( ) on the Looker menu bar.

  2. In the Looker Marketplace, select Manage to open the Manage page.

  3. On the Manage page, click the block’s gear icon to view its configuration settings.

  4. In the Update configurations window, confirm that the block is configured correctly. Click Update after making any changes to save your updates and close the block configuration window.

Top