home User Guide Getting Started Help Center Documentation Community Training Certification
Looker keyboard_arrow_down
language keyboard_arrow_down
Looker documentation will be moving to cloud.google.com in mid-2022!
All the information you rely on will be migrated and all docs.looker.com URLs will be redirected to the appropriate page.
Developing a custom block for the Looker Marketplace

This page describes how to create a custom block that can be added to the Looker Marketplace and accessed by other Looker users.

Please note that you must be a member of the Looker Partner Network or a Looker customer to submit content to the Looker Marketplace.

For information about Looker Blocks that are already built and available for use, see the Looker Blocks documentation page. For information on customizing blocks that you have installed from the Marketplace, see the Customizing Looker Marketplace Blocks documentation page.

To develop a block and make it available to all Looker users through the Looker Marketplace, follow the steps described on this page:

  1. Set up and connect the data source to Looker.
  2. Create a project and add required files.
  3. Make your block accessible.
  4. Submit your block for Looker review.

Setting up and connecting the data source to Looker

Blocks are data models, so they work best when they’re designed for a specific, easily repeatable dataset. Most block installation errors occur when the user’s dataset fails to match the schema, table, and field names in the block.

Once you have determined your data source, connect your data source to Looker so that you can begin modeling. If you need to change any of the default connection settings, make a note in your README file.

Creating a project and adding required files

Create a project to represent your block. Consider using a naming convention such as
block-<database_dialect>-<role> (for example, block-redshift-admin).

Next, create the following files in your project:

Users who install your block can refine the base Explores, views, and dashboards in a separate refinements.lkml file. The following sections explain each required file type in further detail:

Creating a manifest file

Create a manifest file for your project. The manifest file should start with a project name and then define some LookML constants for your users to change. For example, you should define the Looker connection name as a constant with export: override_required so that users can override it with their own connection name.

Here is a sample manifest file:

project_name: "block-ga-360"

################ Constants ################

# Used in google_analytics_block.model connection param
  value: "looker-private-demo"
  export: override_required

# Used in ga_sessions.view sql_table_name
constant: SCHEMA_NAME {
  value: "bigquery-public-data.google_analytics_sample"
  export: override_optional

constant: GA360_TABLE_NAME {
  value: "ga_sessions_*"
  export: override_optional

Creating view and explore files

Create a view.lkml file for each view. If a user’s schema and table names might differ from yours, make sure to define the schema and table names as constants in your manifest file so that users who download your block can update the schema and table names in the autogenerated manifest file. Then, reference those constants in the sql_table_name parameters of your views.

Here is an example of a block view.lkml file:

view: user_facts {

  # SCHEMA_NAME and GA360_TABLE_NAME are constants
  sql_table_name: @{SCHEMA_NAME}.@{GA360_TABLE_NAME} ;;

  dimension: clientID {
    type: string
    sql: ${TABLE.clientId}


Next, create one or more explore.lkml files. Make sure each explore file includes the necessary views for that explore. Design your Explores thoughtfully to contain logical joins, drills, and curated Explore pages. After another user installs the block from the Marketplace, it should be simple for their business users to jump in and start analyzing their data.

You can find a general list of modeling best practices on our Community Forum and in the Looker Help Center, such as Best Practice: LookML Dos and Don’ts and Best Practice: Writing Sustainable, Maintainable LookML.

Here is an example of an explore.lkml file:

include: "/Google_Analytics/Sessions/*.view.lkml"

explore: future_input {  
  view_label: "Audience Traits"
  label: "BQML Customer Likelihood to Purchase"
  description: "This explore allows you to slice and dice likeliness to purchase scores by different customer traits to see how they differ. The default range of data you are looking at is in the past 30 days"
  join: future_purchase_prediction {
    type: left_outer
    sql_on: ${future_purchase_prediction.clientId} = ${future_input.client_id} ;;
    relationship: one_to_one

Creating a model file

Create a model file that includes all view, explore, and dashboard files in your project. Make sure the connection name is referenced as a LookML constant from your manifest file.

Define at least one datagroup to set a caching policy.

Here is an example of a model file:

connection: "@{CONNECTION_NAME}"

include: "/views/*.view.lkml"
include: "/explores/*.explore.lkml"
include: "/dashboards/*.dashboard.lookml"

datagroup: nightly {
  sql_trigger: SELECT TIMEZONE('US/Pacific',GETDATE())::DATE;;

Creating LookML dashboard files

For inclusion in the Looker Marketplace, each block must include a minimum of three LookML dashboards that provide meaningful, helpful analysis. The dashboards should be aesthetic, functional, and comprehensive and should not feature any blurred-out data.

Although there are no hard design requirements for LookML dashboards, Looker recommends these general design best practices:

Custom visualizations are not supported when developing dashboards for Blocks. Use Looker’s native visualization types instead.

See the Dashboard parameters and the Dashboard element parameters documentation pages for more information on customizing LookML dashboards and the visualizations within LookML dashboards, respectively. See the Redshift Admin LookML dashboard file from the Redshift Admin Block for an example of a LookML dashboard file.

Creating a marketplace.json file

Create a marketplace.json file to provide information about how the listing should be displayed in the Marketplace. Each block in the Looker Marketplace must provide this additional information to help users select the block that best fits their needs. Your marketplace.json file should contain:

Here is an example of a marketplace.json file for the Google BigQuery Performance block:

{ "label": "Google BigQuery Performance", "category_label": "Models", "branding": { "image_uri": "https://marketplace-api.looker.com/block-icons/google-cloud.png", "tagline": "This Block provides a comprehensive overview of all cost and performance data for one or multiple BQ projects, enabling users to effectively monitor BigQuery usage down to a per user level. It can be used to set up alerts to long running or high cost queries." }, "constants": { "CONNECTION_NAME": { "label": "Connection Name", "value_constraint": "connection" }, "SCHEMA_NAME": { "label": "Schema Name" }, "AUDIT_LOG_EXPORT_TABLE_NAME": { "label": "Audit Log Export Table Name", "description": "The table name of your BQ Optimization data (typically cloudaudit_googleapis_com_data_access_*)." } }, "models": [ { "name": "block_bigquery_optimization_v2", "connection_constant": "CONNECTION_NAME" } ] }

The following screenshot shows the Marketplace listing that would be generated by this marketplace.json file.

Creating a LICENSE file

All Looker Blocks must be licensed under the MIT open source license. Include the text from this license in a file named LICENSE. See the Redshift Admin Block LICENSE file for an example of a LICENSE file.

Creating a README file

The README file should contain all instructions for implementing the block and should explicitly identify where any customizations are needed, such as in the autogenerated manifest file](#the_autogenerated_manifest_file) or the refinements file. See the Redshift Admin Block README file for an example of a README file.

Things to consider for your README:

Autogenerated files

When users install your block, their Looker instance creates a new Looker project with your project’s files as read-only files. It will also autogenerate the following files for your user:

Users who install your block from the Looker Marketplace can use the refinements.lkml file to refine your LookML and can even add new LookML files. See the Customizing Looker Marketplace Blocks documentation page for more information about how users can customize your block.

The autogenerated manifest file

The autogenerated manifest file allows users who install your block to set variables such as the connection name. The LookML constants defined in the block manifest file can either be edited in the autogenerated manifest file, or set by your users in the block download user interface.

The refinements file

The autogenerated refinements.lkml file allows users who install your block to refine views and Explores that are defined your block. This is where users who download your block will do the bulk of LookML customization to fit their use case.

Here is an example of an autogenerated refinements.lkml file:

include: "//ga360-v2//*.view.lkml" include: "//ga360-v2//*.explore.lkml" # Use LookML refinements to refine views and explores that are defined in the remote project. # Learn more at: https://docs.looker.com/data-modeling/learning-lookml/refinements # # # For example we could add a new dimension to a view: # view: +flights { # dimension: air_carrier { # type: string # sql: ${TABLE}.air_carrier ;; # } # } # # Or apply a label to an explore: # explore: +aircraft { # label: "Aircraft Simplified" # } #

Making the block project accessible

Host your block LookML on a publicly accessible GitHub repository.

All Looker Blocks must be licensed under the MIT open source license, and the license text must be included in a LICENSE file in the repository.

Submitting the block for review

Once your block is ready for submission, follow the instructions at Submitting content to the Looker Marketplace to create supporting documentation for your block, submit your block to the Looker team for review, and publish your block to the Looker Marketplace.