home User Guide Getting Started Help Center Documentation Community Training Certification
Looker keyboard_arrow_down
language keyboard_arrow_down
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.

Looker Blocks™ are pre-built data models for common analytical patterns and data sources. Blocks provide a means for quick-start analysis on many popular third-party SaaS apps. This page describes how to create a custom block of pre-built LookML that can be added to the Looker Marketplace and accessed by other Looker users. The Looker Marketplace is a central location for finding, deploying, and managing many types of Looker content, such as Looker Blocks, applications, visualizations, and plug-ins.

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

Content that is deployed through the Marketplace is expected to fulfill some specific requirements to enable utilization across the Looker user base. At a high level, any block added to the Looker Marketplace must provide examples of comprehensive data analysis based on a robust LookML model or series of models.

Blocks available from the Looker Marketplace tend to focus on these use cases:

For these industries:

If you would like 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 your block projects.
  3. Develop your data model.
  4. Develop LookML dashboards.
  5. Draft content for the Block Directory and Marketplace listing.
  6. Make your block projects accessible.
  7. Submit your block for Looker review.
  8. Maintain your block.

Setting up and connecting the data source to Looker

Looker Blocks are essentially data models, so they must map directly to specific schemas in a database. If a schema is not built so that its fields can be mapped directly to the fields in the block, the block may not work to its full capability out-of-the-box. For example, if a block has a field called user, but the schema refers to that field as customer, then the mapping will be incorrect and the block will not know which field to reference.

To map blocks directly to schemas, you can pair each block with a specific ETL (extract, transform, load) provider. ETL is the process by which data is taken from a data source and loaded into a schema in a database. Each Looker Block provides details around the schema and associated ETL providers. Block installation errors are usually the result of a mismatch between the block and the database schema. Be sure to check that your ETL provider matches the provider detailed in the block.

  1. Identify a third-party data source for which you’d like to create a block.
  2. Determine the appropriate ETL method.
    • When data is extracted from a third-party data source, it should be placed in a database with a consistent schema. Blocks are tied to specific schemas. A schema needs to be as stable and static as possible, so that block developers can create full, repeatable data models that can be deployed for any user of the data source and ETL vendor. If the building of this block is not tied to a specific ETL vendor, you must prescribe a schema that any user can follow.
  3. Connect the database to Looker.

    • Connect the database to Looker so that you can begin modeling.

    It is expected that you will maintain this database and keep it in production.

Creating the custom block projects

The Looker Marketplace aims to ensure that blocks can be versioned and updated in one place and available to all users while still being customizable for each user’s specific needs. To accomplish this, you can create two projects to represent your block: a read-only CORE project that can be updated from a master Git repo, and a writeable CONFIG project that extends the read-only project and can be customized as much as needed.

To import projects, your Looker admin must enable the Local Project Import Labs feature.

Explores and views are created in the CORE project, are extended in the CONFIG project, and are extended again through the CORE project (the “content layer”):

See the Example: Block project extends with Explores section on this page for more information about how the block’s projects extend one another.

The CORE project

The read-only CORE project has the naming convention block-database_dialect-role (for example, block-redshift-admin) and contains the block’s core analytical code and definitions of its base Explores, views, and dashboards. The CORE project contains these items:

The CORE project’s base Explores and views are defined in the CORE project and extended in the CONFIG project, where they can be modified. Then the CONFIG project and its files are imported into the CORE project. Finally, the CORE project defines the block’s content layer: the dashboards and Explores that are surfaced in the Explore menu of the Looker UI.

To create the block’s content layer, the block’s CORE project contains Explores and views that extend the CONFIG project’s Explores and views, allowing changes that are made in the CONFIG project to be brought into the block’s Explores and dashboards.

The CONFIG project

The writeable CONFIG project has the naming convention block-database_dialect-role-config (for example, block-redshift-admin-config) and contains views, Explores, and dashboards that extend the LookML defined in the CORE project. Its files are also imported in the CORE project and extended in the CORE project’s content layer, so that changes made to files in the CONFIG project are brought into the CORE project.

The CONFIG project contains these files:

Users who install your custom block from the Looker Marketplace can add custom LookML to mix in additional data within the CONFIG project or tweak the block’s core analytical model by extending or joining in CORE project Explores and views to create new Explores or view files. See the Customizing Looker Marketplace Blocks documentation page for more information about how users can customize your custom block.

Example: Block project extends with Explores

Suppose you are creating a block that contains an Explore called Orders. The dashboards and Explores for a block that are visible in the Explore menu of the Looker UI are based on the final layer of the following extension chain:

Developing the data model

Configure the data model 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. Explores should be curated and intuitive, as opposed to exposing every single field.

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.

Leveraging LookML constants

Users must be able to customize your block after they install it from the Marketplace. To allow users to customize your block, you can leverage the LookML constant parameter. Constants allow you to declare the fields that need to be customized by a LookML developer after the block is installed on their instance. This also provides a single location — the CONFIG project’s manifest file — for users to update the value of these fields. Constants can be referenced throughout a project using the syntax @{constant_name}. See the next section about Passing constants between projects for more information.

Some customizations may be as simple as changing the name of the connection in the Looker model file. Other times, it means also changing schema names or table names. For example, not every user of your block will be using the same database connection, so you can declare a constant in your CORE project manifest file called connection_name with the value of looker_app (whatever the user calls their database). Likewise, users’ databases might use different schemas or have unique table name prefixes or suffixes. The constant syntax would be:

# Used in google_analytics_block.model connection param constant: CONNECTION_NAME { value: "looker_app" export: override_required } # Used in ga_sessions.view sql_table_name constant: GA360_SCHEMA_NAME { value: "ga360_generated_2" export: override_required } # Make sure to include a note in the README about having * to include all partitioned tables constant: GA360_TABLE_NAME { value: "GA_SESSIONS*" export: override_required }

See the constant parameter documentation page for more information about how to use LookML constants.

Passing constants between projects

To pass constants between projects, the CORE project’s manifest file imports the CONFIG project using the local_dependency parameter and sets an override_constant subparameter to override any constants referenced in the imported CONFIG files with the values defined by the CORE project’s constants.

To import projects, your Looker admin must enable the Local Project Import Labs feature.

For example, the CORE project manifest file will have:

local_dependency: { project: "CONFIG_project_name" override_constant: schema_name { value: "core_schema_name" } }

And the CONFIG project manifest file will have:

constant: schema_name { value: "config_schema_name" export: override_required }

See the constant parameter documentation page, for how best to specify whether a constant’s value can be overridden when a user imports your block’s projects.

Developing LookML dashboards

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:

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.

Drafting content for the Looker Block directory and Marketplace

In addition to listing some blocks on the Looker Marketplace, Looker hosts each block in the Looker block directory. Each block in the directory must provide the following information to help users select the block that best fits their needs.

Create a marketplace.json file to provide information about how the listing should be displayed in the Marketplace, such as:

Here is an example marketplace.json file for the Google Query 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_*)." }, "config_project_name": { "label": "Config Project Name" } }, "models": [ { "name": "block_bigquery_optimization", "connection_constant": "CONNECTION_NAME" } ], "auxiliary_projects": [ { "git_uri": "git://github.com/looker/block-bigquery-optimization-config.git", "git_ref": "bb12e945fb7cc3cc706b3556e0f17c5ed42a128d", "label": "Google BigQuery Performance Config", "constant_name": "config_project_name" } ] }

Marketplace label, category_label, and branding fields

In the screenshot below, "label" corresponds to Google BigQuery Performance and "category_label" corresponds to Models. Within "branding", the field "image_uri" specifies a URI for the Google Cloud image, and the field "tagline" corresponds to the text “This block provides a comprehensive overview…”:

Marketplace constants field

You can use the constants JSON field to allow users to provide input about their use case, such as the connection where their data lives. When constants are specified in the marketplace.json file, users are prompted to provide values for these fields during the installation process:

Marketplace models field

Each model may access only one connection on the instance, so the "models" field has a constant, "connection_constant", that specifies the connection in the "connection_name" constant field.

Marketplace auxiliary_projects field

When users install your Marketplace block, a non-editable CORE project containing your block’s LookML is created. To allow users to customize the CONFIG project, they’ll need access to the CONFIG project as well.

The "auxiliary_projects" field instructs Looker to create a project populated via the sources specified with the "git_uri" and "git_ref" fields. Specify the name of your block’s CONFIG project in the constants section for auxiliary project names — in the example above, the constant is "config_project_name".

Making the block projects accessible

Block LookML must be housed in a publicly accessible GitHub repository, and all Looker Blocks must be licensed under the MIT open source license. Include the text from this license in the repository’s README file or in a separate license file. The README file should also contain all instructions for implementing the block and should explicitly identify where any customizations are needed. See the Google GA 360 Block README for an example README file.

Submitting the block for review

Send a link to the GitHub repository to your Partner Manager or to Looker’s product team through your designated Account Manager, and include at least three screenshots (minimum 720 x 720 resolution) illustrating your block’s content and function. Looker will review the submission and provide edits and feedback (if applicable). Once any edits have been addressed, Looker will post the block to the Block Directory and the Looker Marketplace within one to two weeks.

Maintaining the block

Once your block is deployed and available for Looker users, it is expected that your team will evaluate and rectify any reported errors. Typically this requires minor updates to your block LookML. For example, if a user reports that a join is causing an unnecessary fanout, you may need to change that join type or tighten up the join logic some other way. Users will submit these as comments in the Github repo where the block is hosted. Looker requests that you respond to these comments within 14 calendar days.

If you need to make updates to your block, push the changes to the block’s Github repository and then contact your Partner Manager or Account Manager, providing one to three sentences describing what this update accomplished. When Looker publishes this change, the block’s listing will prompt users to update the block the next time it they use it.

To ensure that Looker’s sales representatives and analysts are best able to demonstrate the value of the block, Looker requests access to a “live” deployment in which Looker may demo the block. This environment typically lives in your Looker instance, where data is hooked up to Looker.