The Looker IDE supports folders for your project files. Folders are shown in the left navigation pane of the IDE. If your Looker developers have not organized your project files into folders, your project will have a flat file structure, with files listed alphabetically in the File Browser panel.
If you want to organize your project into folders, see the Organizing an existing project with IDE folders section on this page for recommendations.
Here is an example project where a developer has added folders for different types of project files, such as explores
, models
, and views
:
You can show or hide the IDE file browser either by using the keyboard shortcut Command-B (Mac) or Ctrl+B (Windows) or by clicking the file browser icon:
Click the icons in the toolbar at the top of the File Browser panel to collapse all folders, perform bulk edits, search for a project file, or create new folders and new files:
Each file or folder in the left side panel has a menu that displays the available actions for that item. Click the three-dot menu to the right of the filename to open the menu. For an item that has a long name or that is nested in multiple folders, you can access the menu by scrolling in the left panel:
As you organize your LookML files with folders, you need to commit your changes and deploy them to production before other Looker developers can see them. This is just like any change you make to your LookML project.
Imported projects folder
If you import a project, the Looker IDE automatically creates an imported_projects
folder. Files from both local projects and remote projects are listed in the imported_projects
folder. Click on an imported project file to view its contents:
Because they cannot be edited, imported project files are not visible when you are bulk-editing files in the IDE.
Managing files and folders
File and folder naming conventions
When creating files and folders, keep the following in mind:
- LookML is case sensitive. Be sure to adhere to your project’s conventions when naming your folders. For example, if your convention is to use all lowercase letters in your project, you would want to name your folder
views
instead ofViews
. This makes a difference especially when you need to specify a file’s path, such as when including files. Generally, it’s a good idea to consistently use lowercase letters when you name LookML objects and folders. - Filenames cannot include spaces or any of the following characters:
/
?
*
:
|
"
<
>
%
- When creating LookML files with the Looker IDE, Looker will automatically add the
.lkml
extension to the end of the filename if you don’t include the extension manually. For example, if you enter the file nameflights_data_tests
, Looker will name the fileflights_data_tests.lkml
. - To create an Explore file, the file must have the
.explore.lkml
extension at the end of the filename. If you are uploading the file, you must use the full.explore.lkml
extension. If you are using the Looker IDE to create the file via the Generic LookML files option, Looker will add.lkml
to the end of the filename if the extension isn’t there, but you still must manually add the.explore
part of the extension to the filename. For example, to create an Explore file calledflights
using the Looker IDE, you can enter eitherflights.explore
orflights.explore.lkml
, and the file will be namedflights.explore.lkml
. - It is recommended that you use the Looker IDE to add files to your LookML project, either by creating them in the Looker IDE or by uploading them in the Looker IDE. If you instead create files outside of the Looker IDE and then use the Looker IDE to Pull from (production branch), be sure to use the correct naming conventions and include the
.lkml
extension in the filename (orexplore.lkml
for Explore files). If a filename includes unsupported characters, the Looker IDE file browser will show the filename in red, and you will not be able to see the contents of the file until you rename the file with supported characters. In addition, the Looker IDE will not display the file at all if the file does not have the.lkml
extension.
Creating folders
You can create folders for different file types (such as view files or model files). You can even create subfolders, which is very useful if you want to include
a subset of your views.
When creating folders, keep in mind that LookML is case sensitive. Be sure to adhere to your project’s conventions when naming your folders. For example, if your convention is to use all lowercase letters in your project, you would want to name your folder
views
instead ofViews
. This makes a difference especially when you need to specify a file’s path, such as when including files. Generally, it’s a good idea to consistently use lowercase letters when you name LookML objects and folders. See the naming conventions for limitations and guidelines for naming your files and folders.
To create a folder:
- Select the Create Folder option from the appropriate menu:
- To create a new folder at the top level of your directory structure, use the + menu at the top of the File Browser panel.
- To create a new subfolder under an existing folder, use the three-dot menu for the existing folder.
- Enter a name for the new folder.
- Click Create.
The new folder is added to the navigation pane.
Creating files
If your Looker admin has enabled the Improved LookML Generation Labs feature, the + menu at the top of the File Browser panel will show an option to Generate LookML from Database in addition to the options listed here.
To create a new file in your LookML project:
Select the appropriate menu:
- To create a new file at the top level of your directory structure, use the + menu at the top of the File Browser panel.
- To create a new file under an existing folder, use the three-dot menu for the existing folder.
Select the type of LookML file you want to create. You can create the following types of files:
- Model files
- View files based on database tables
- View files
- Project manifest files
*
- Dashboard files
- Document files
- Locale strings files
**
- Generic LookML files, which are used for the following types of files:
*
Project manifest files can be created only from the + icon at the top of the file browser in the Looker IDE, and only if the project doesn’t have a manifest file already. This is because a project can have only one manifest file, and the manifest file must be located at the root level of the project’s directory structure.**
The Create Locale Strings File option is available only from the + icon at the top of the file browser in the Looker IDE, but once a locale strings file is created (or uploaded), you can move the file to a folder.In the Create File pop-up, enter a name for the new file. See the file naming conventions for limitations and guidelines for naming your files.
Click Create. The new file will be displayed where you created it. If needed, you can easily move it to another folder.
Once you create the file, be sure to use the
include
parameter if you want to reference elements from the file in other LookML files of your project. See theinclude
parameter documentation page for more information.
Uploading files
You can also upload files to your project from your computer. This is helpful if you have created JSON data files or LookML files locally on your computer.
See the naming conventions for limitations and guidelines for naming your files.
To upload a file to your project, use the drag-and-drop function in the Looker IDE:
- Navigate to your project files.
- Drag the file from your computer into the Looker IDE. The file will be displayed at the root of your directory structure.
- Once the file is uploaded, move the item to another folder.
Once you upload the file, be sure to use the
include
parameter if you want to reference the file or elements from the file in other LookML files of your project. See theinclude
parameter documentation page for more information.
Deleting files and folders
Delete a folder or a file by selecting Delete from the item’s three-dot menu in the left panel of the IDE.
Deleting a folder also deletes its contents, so be careful when deleting folders. Before deleting a folder, do the following:
• Verify that you want to delete the files in the folder, or move the files to a different location before deleting the folder.
• Verify that the folder does not contain any files that are referred to ininclude
statements in your project. See the Usinginclude
with IDE folders section on this page for information on usinginclude
with IDE folders.
When you delete a folder, the IDE shows a confirmation pop-up. The pop-up specifies how many items are included in the deletion, which includes the folder and any files inside the folder.
Moving items in a foldered project
You can drag and drop a single file or an entire folder with all its contents into new locations:
Drag and drop a file or a folder into another folder. The destination folder does not need to be expanded to receive other folders or files. A folder automatically expands when items are hovered over it.
When you change a file’s path, be sure to update any
include
statements in your project to match the new file path. See the Usinginclude
with IDE folders section on this page for information on usinginclude
with IDE folders.Also, be aware that when you change a file’s path, Git effectively deletes the file and creates a new file with the new file path. This means that the Git history for the file will be empty, because Git considers it a new file. To see the file’s Git history before it was moved, use your Git interface to navigate to the file in its original location and view the Git history from there. (The same logic applies for a renamed file, since Git effectively deletes the file and creates a new file with a different name.)
Bulk editing files and folders
You can also select multiple folders and files to move into new locations, or to delete.
Moving files and folders in bulk
To move folders and files in bulk:
- Click the Bulk Edit icon at the top of the File Browser panel.
- Select the items to move. The number of files selected is displayed in purple next to the Select Files header.
- To select or deselect individual files, expand their folders and click the checkbox next to the filenames.
- To select or deselect entire folders and their contents, click the checkbox next to the folder name.
- To select an entire section of the directory list, use Shift-click. Click the checkbox for the top item in the range, then hold down the Shift key and click the checkbox for the last item in the list. Both items and all items in between will be selected. You can also just Shift-click on an item to select the item and everything above it in the directory list.
- Click the Bulk Move Items folder icon to select option. The IDE will then display a folder selection pop-up menu.
- In the pop-up menu, choose a folder for the selected items, or click New Folder to create a new folder. The project name will display the file path of the folder you have selected at the top of the next menu page. To move items to the root directory of your project, click Move without a folder selected.
- Confirm the selected destination by clicking Move, create a new folder within the selected folder by clicking New Folder, or return to the main folder options menu by clicking the project name link in the file path.
- Click the X in the Select Files header to exit bulk edit mode.
After you change a file’s path, be sure to update any
include
statements in your project to match the new file path. See the Usinginclude
with IDE folders section on this page for information on usinginclude
with IDE folders.Also, be aware that when you change a file’s path, Git effectively deletes the file and creates a new file with the new file path. This means that the Git history for the file will be empty, because Git considers it a new file. To see the file’s Git history before it was moved, use your Git interface to navigate to the file in its original location and view the Git history from there. (The same logic applies for a renamed file, since Git effectively deletes the file and creates a new file with a different name.)
Deleting files and folders in bulk
To delete folders and files in bulk:
Deleting a folder will delete all its contents. Before deleting a folder, verify that you want to delete the files in the folder. If you want to keep them, move the files to a different location before deleting the folder.
- Click the Bulk Edit icon at the top of the File Browser panel.
- Select the items to delete. The number of files selected is displayed in purple next to the Select Files header.
- To select or deselect individual files, expand their folders and click the checkbox next to the filenames.
- To select or deselect entire folders and their contents, click the checkbox next to the folder name.
- To select an entire section of the directory list, use Shift-click. Click the checkbox for the top item in the range, then hold down the Shift key and click the checkbox for the last item in the list. Both items and all items in between will be selected. You can also just Shift-click on an item to select the item and everything above it in the directory list.
- Click the Delete Items trash icon. The IDE will then display a pop-up menu listing the items selected.
- Confirm the items to be deleted by clicking Yes, Delete, or return to item selection by clicking Cancel.
- Click the X in the Select Files header to exit bulk edit mode.
Using include
with IDE folders
Once you have organized your project files into folders, you need to provide the file’s path when using the include
statement.
When using
include
, keep in mind that LookML is case sensitive. When specifying a file’s path, you must match the case of the file and of the folders in the path. For example, if your file is in theViews
folder, you must match this capitalization in theinclude
parameter. So you would specifyinclude: "/Views/accidents.view"
. Generally, it’s a good idea to stick with lowercase when naming LookML objects and folders.
You can use absolute or relative paths in the include
statement (see the Path syntax section on this page for examples), and you can use the wildcards *
and **
to include multiple files at once (see the Wildcard examples section on this page for examples).
For example, if you have this directory structure in your project:
The following statements will include the products
view, the order_facts
view, and all views in the /views/users/
directory:
When you change a file’s path, be sure to update any include
statements in your project to match the file’s new path. You may see LookML validation warnings on your old include
statements if they no longer refer to existing files or file paths. In addition, you may see LookML validation errors for referenced objects that can no longer be found because their file paths have changed.
Handy Tip: When using wildcards, you can check which files are included by hovering over the information icon in the change bar of the file, or by clicking on the
include
statement and looking in the quick help:
Path syntax
Here are some example syntaxes you can use for including files:
Syntax | Description |
---|---|
PATH |
Relative path starting from current file’s location. |
./PATH |
Relative path starting from current file’s location. This example points to the same file as the above example: PATH . |
../PATH |
Relative path starting from current file’s parent directory. |
/PATH |
Absolute path starting from current project’s root. |
//PROJECT_NAME/PATH |
Absolute path starting from the root of an imported project called PROJECT_NAME . |
Wildcard examples
If you are using LookML refinements, do not use wildcards in your includes. LookML refinements leverage the order of includes, and using wildcards in your includes does not allow you to control the order in which each file is included. See the LookML refinements documentation page for more information about refinements.
Here are some examples using wildcards (note that you can replace PATH
with the path syntaxes in the previous table):
Syntax | Description |
---|---|
PATH/*.view |
Wildcard matching files ending with .view at PATH . |
PATH/*.view.lkml |
Wildcard matching files ending with .view.lkml at PATH . Because view files have the extension .view.lkml , this example specifies the same file as the previous example, PATH/*.view . The .lkml part is not displayed in the IDE, nor is the .lkml part required for include statements. However, you can use wildcards to leverage this common part of the file extension. See the LookML project files documentation page for a list of project file extensions. |
PATH/*.lkml |
Wildcard matching files ending with .lkml at PATH . Note that several file types share .lkml as the final part of the file extension, such as .view.lkml and .model.lkml . The .lkml part is not displayed in the IDE, nor is the .lkml part required for include statements. However, you can use wildcards to leverage this common part of the file extension. See the LookML project files documentation page for a list of project file extensions. |
PATH/myfile.* |
Wildcard matching files called myfile with any extension type at PATH . |
PATH/myfile.*.lkml |
Wildcard matching files called myfile with any .lkml extension type at PATH . |
PATH/my*file.view |
Wildcard matching files starting with my and ending with file.view at PATH . |
PATH/my*fi*le.view |
Wildcards matching files starting with my , followed by some characters, then fi , some additional characters, and ending with le.view at PATH . |
PATH/*/myfile.lkml |
Folder name wildcard (match only a single level of nesting). Matches all myfile.lkml files in any direct child directories of PATH . |
PATH/**/my_file.view |
Recursive wildcard matching (match any amount of nesting) for all files called my_file.view.lkml at PATH and all subdirectories. |
PATH/**/*.view |
Recursive wildcard matching all files ending with .view.lkml at PATH ’s subdirectories. |
PATH/**/my_folder/myfile.view |
Recursive wildcard matching the subpath /my_folder/myfile.view at any depth under PATH . |
Using map_layer
with IDE folders
If you have IDE folders enabled for your project, you need to use the file path when you specify a project file for map_layer
:
Organizing an existing project with IDE folders
If your project previously had the legacy flat file structure, you can choose to keep this structure; but if you choose to organize your project files into folders, we strongly recommend that you make the following preparations:
- Plan the file structure ahead of time with all developers.
- Ensure that all your Looker developers have deployed all their updates to production. If a developer has undeployed changes, their branch(es) will reflect the file structure that existed when they last pulled from production. If the project had a flat file structure at that time, the developer’s version of the file will be pushed to production in its original location, so you will end up with two copies of the file. In addition, if a developer has undeployed changes during the migration to folders, that developer will face a merge conflict when they pull from production after the migration.
- Enact a temporary code freeze with all your developers until the project has been fully migrated to the new directory structure.
- Assign a single developer to move the files. The procedure below assumes a single developer will be migrating the project to IDE folders. If you need to have multiple developers move files, divide the task among the developers to avoid merge conflicts. If you do encounter merge conflicts, see the Using version control and deploying documentation page for information on resolving them.
Be aware that when you move a file in Git, you are effectively deleting the file and creating a new file with a new file path. This means that the Git history for the file will be empty, because Git will consider it a new file. To see the file’s Git history before it was moved, use your Git interface to navigate to the file in its original location and view the Git history from there.
Once all your developers have pushed and committed their changes and paused all work on the project, you can then migrate the project to its new directory structure.
Assign a single developer to do all the following steps:
- Verify that all updates on all development branches have been deployed to production. This includes the development branches of the developer performing the migration to IDE folders.
- Verify that all other developers have stopped making changes to the project.
- Pull from production.
- Create the project’s folders.
- Move the project files into the folders, either one file at a time or using bulk edit.
- Validate the project’s LookML. It is expected that you will have multiple LookML errors and warnings, since the
include
andmap_layer
statements use references to file locations that likely will have been moved during this procedure. Update any
include
andmap_layer
statements in your project to match the file’s new path. In addition, you may see LookML validation errors for referenced objects that can no longer be found because their file paths have changed. See the Usinginclude
with IDE folders section on this page for information on usinginclude
with IDE folders, and the Usingmap_layer
with IDE folders section on this page for information on using map layers with IDE folders.Handy Tip: You can use wildcards to create a temporary fix for LookML validation warnings and errors resulting from
include
statements. Using view files as an example, you can specifyinclude: "/**/*.view"
to include all files in all your project folders. This will prevent LookML validation problems while you continue developing. However, this is not a recommended solution for the long term, since including more files than are needed can affect performance.- Deploy the updates to production.
- Inform the other Looker developers that they can now pull the updates from production and resume developing in the project.