Merge pull request #48 from lightdash/new-rename-guide

rename docs

Author: oli-rmsy

guides/renaming-models-and-fields.mdx

@@ -0,0 +1,80 @@
+---
+title: "Renaming models, metrics, and dimensions"
+---
+
+This guide explains two workflows that can be used to rename metrics, dimensions, or models across your entire project. All field or model references will be updated across charts, dashboards, and scheduled deliveries. This feature is particularly useful when you need to standardize naming conventions or fix typos.
+
+<Info>
+  Most content can also be renamed using [Dashboards as code](/references/dashboards-as-code), however, the rename methods in this doc require fewer steps and will automatically respect the right syntax for different field types. More importantly, it will update some content that is not exposed on Dashboards as code, like scheduled delivery filters.
+
+  Chart names and descriptions will not be updated using these rename workflows. If you want to update those in bulk, we recommend using Dashboards as code.
+</Info>
+
+
+## Rename in Lightdash
+
+If you change field or table names in dbt, you will notice validation errors in your charts that use those fields or tables. You can fix these directly on the validation page by renaming references in the broken charts. You can easily access the validation page by clicking on the bell on the navigation bar.
+
+<img
+  src="/images/rename-validation-errors.png"
+  alt="rename validation errors"
+  className="mx-auto"
+  style={{ width:"50%" }}
+/>
+
+On the navigation page, hover over the chart you want to fix, and click on the **Fix** button.
+
+![rename fix button](/images/rename_fix_button.png)
+
+A popup menu will appear, where you can choose to rename a field or model using an **existing** value.
+
+<img
+  src="/images/rename_modal.png"
+  alt="rename modal"
+  className="mx-auto"
+  style={{ width:"50%" }}
+/>
+
+Optionally, you can click **Fix all ocurrences** to rename the same field or table on all content, including other charts, dashboards and scheduled deliveries. 
+
+If you have made mulitple field or table changes to the same chart (eg: you changed 2 metrics), you will have to perform multiple rename actions. 
+
+After renaming, consider running validation again to ensure everything works as expected.
+
+
+## Rename in the CLI
+
+The Lightdash CLI provides an alternative and more flexible way to rename models or fields across your project. This is a more advanced option to the UI and affects all the content in the project. The CLI will also allow you to rename content before changes happen to dbt. 
+
+
+### Important CLI callouts
+
+- Renaming is project-wide by default, but can be scoped to a specific model using the `--model` option.
+- Always use `--dry-run` first to understand the impact of your changes.
+- You can use `--list` on your actual run to get a full list of everything that was updated.
+- Only lowercase letters (a-z) and underscores `_` are allowed in field and table names.
+
+
+### Example CLI Workflow
+
+This is a sample of how you can take the most from this feature, when renaminig content on your dbt project. 
+
+1. Rename a field in your dbt project YML file: `user_id` becomes `customer_id`.
+2. Create a preview environment to test those changes.
+3. Existing charts will fail, you can go into validation to confirm which ones are affected.
+4. Run `lightdash rename --type field --from user_id --to customer_id -p <preview-project-id> --dry-run`  to list the affected charts. 
+5. If you are happy with the changes, run rename without `--dry-run`.
+6. Confirm all charts are referencing new fields (they might still error if you haven't updated your warehouses using dbt run).
+7. Merge the code, run dbt, then run `lightdash rename --type field --from user_id --to customer_id -p <production-project-id> --list` on your main project.
+  - The `--list` option gives you a full list of content that was changed.
+
+The CLI will show you which charts, dashboards, alerts, and dashboard schedulers will be updated and also, we will generate a JSON log that contains the affected chart and dashboard names and UUIDs, you can use those UUIDs to manually revert some of the charts to a previous version. 
+
+![rename CLI list](/images/rename_cli_list.png)
+
+[Read the CLI reference doc](/references/lightdash-cli#lightdash-rename) for all arguments and more examples.
+
+
+## Reverting changes 
+
+When renaming, a new chart version is created with the new changes. If you made a mistake renaming, you could run rename again, or you could restore individual charts using [version history](https://docs.lightdash.com/guides/version-history#chart-version-history)

images/rename-validation-errors.png

@@ -5,22 +5,23 @@ description: "The Lightdash CLI is the recommended way to develop your Lightdash
 
 ## Dependencies
 
-The Lightdash CLI requires the [dbt core](https://docs.getdbt.com/docs/core/installation-overview) or the [dbt cloud CLI](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) to be installed and available under the `dbt` command.
+The Lightdash CLI requires Node, NPM, and the [dbt core](https://docs.getdbt.com/docs/core/installation-overview) or [dbt cloud](https://docs.getdbt.com/docs/cloud/cloud-cli-installation) CLI to be installed and available under the `dbt` command.
 
-### Known limitations when using **dbt cloud CLI**
+### Known limitations when using dbt cloud CLI
 
-#### Warehouse credentials dependency for some commands
+**Warehouse credentials dependency for some commands**
 
 Affected commands: `lightdash generate`, `lightdash preview` and `lightdash start-preview`
 
 These commands rely on the warehouse credentials from the active project, as the dbt Cloud CLI does not expose credentials directly. Ensure the project's credentials have access to all development and staging schemas for a seamless experience.
 
-#### Empty warehouse credentials for new projects
+**Empty warehouse credentials for new projects**
 
 Affected commands:  `lightdash deploy --create`
 
 When using this command to create a new project that is not a preview, the warehouse credentials will not be populated automatically. Users must update the warehouse credentials manually in the project settings page after the project is created.
 
+
 ## Global options
 
 There are three global options that can be used with any Lightdash CLI command: [version](#version), [help](#help), and [verbose](#verbose).
@@ -96,13 +97,13 @@ For examples and command-specific options, click through the command in the tabl
 |[`lightdash stop-preview`](/references/lightdash-cli#lightdash-stop-preview)             | Shut down an open preview project                                                  |
 |[`lightdash deploy`](/references/lightdash-cli#lightdash-deploy)                         | Compile and deploy a Lightdash project using your local project and credentials    |
 |[`lightdash refresh`](/references/lightdash-cli#lightdash-refresh)                       | Refresh Lightdash project with remote repository                                   |
-|[`lightdash validate`](/references/lightdash-cli#lightdash-validate)                     | Validates content from your active project against your local project files        |
-|[`lightdash generate`](/references/lightdash-cli#lightdash-generate)                     | Generates or updates schema.yml file(s) for the selected model(s)                  |
-|[`lightdash dbt run`](/references/lightdash-cli#lightdash-dbt-run)                       | Runs dbt and then generates or updates schema.yml file(s) for the selected model(s)|
-|[`lightdash generate-exposures`](/references/lightdash-cli#lightdash-generate-exposures) | [Experimental command] Generates a .yml file for Lightdash exposures               |
-|[`lightdash download`](/references/lightdash-cli#lightdash-download)                     | Downloads all charts and dashboards from your Lightdash project as code            |
-|[`lightdash upload`](/references/lightdash-cli#lightdash-upload)                         | Uploads all updates to charts and dashboards as code to your Lightdash project     |
-
+|[`lightdash validate`](/references/lightdash-cli#lightdash-validate)                     | Validate content from your active project against your local project files         |
+|[`lightdash generate`](/references/lightdash-cli#lightdash-generate)                     | Generate or update `schema.yml` file(s) for the selected model(s)                  |
+|[`lightdash dbt run`](/references/lightdash-cli#lightdash-dbt-run)                       | Run dbt, then generate or update `schema.yml` file(s) for the selected model(s)    |
+|[`lightdash generate-exposures`](/references/lightdash-cli#lightdash-generate-exposures) | [Experimental command] Generates a YAML file for Lightdash exposures               |
+|[`lightdash download`](/references/lightdash-cli#lightdash-download)                     | Download all charts and dashboards from your Lightdash project as code             |
+|[`lightdash upload`](/references/lightdash-cli#lightdash-upload)                         | Upload charts and dashboards as code to your Lightdash project                     |
+|[`lightdash rename`](/references/lightdash-cli#lightdash-rename)                         | Rename model or field names across all your Lightdash content                      |
 ---
 
 ### `lightdash login`
@@ -365,6 +366,7 @@ All standard [dbt options](#dbt-options) work with `lightdash validate`.
   - (default: ["charts","dashboards","tables"])
   - Specify project elements to validate.
 
+
 **Example:**
 
 Validate only dashboards and use the existing compiled dbt manifest:
@@ -373,12 +375,14 @@ Validate only dashboards and use the existing compiled dbt manifest:
 lightdash validate --only ["dashboards"] --skip-dbt-compile
 ```
 
+
 ### `lightdash generate`
 
 Generates a new `schema.yml` file or updates existing `schema.yml` for selected model(s).
 
 All standard [dbt options](#dbt-options) work with `lightdash generate`.
 
+
 **Options:**
 
 - `-y` or `--assume-yes`
@@ -388,6 +392,7 @@ All standard [dbt options](#dbt-options) work with `lightdash generate`.
   - (default: false)
   - exclude Lightdash metadata from the generated .yml
 
+
 **Example:**
 
 Generate or update YAML file for a single dbt model to cover all columns in the database:
@@ -408,6 +413,7 @@ Generates a `schema.yml` file for Lightdash exposures.
 
 This command does not support using dbt options.
 
+
 **Options:**
 
 - `--project-dir [path]`
@@ -416,6 +422,7 @@ This command does not support using dbt options.
 - `--output [path]`
   - The path where the output exposures YAML file will be written
 
+
 **Example:**
 
 Create or update YAML file called `lightdash-exposures.yml` in the current directory with all exposures in Lightdash:
@@ -424,12 +431,14 @@ Create or update YAML file called `lightdash-exposures.yml` in the current direc
 lightdash generate-exposures --output ./lightdash-exposures.yml
 ```
 
+
 ### `lightdash dbt run`
 
 Runs dbt and then generates or updates `schema.yml` file(s) for models that have columns missing or changed from the existing `schema.yml` files.
 
 Any dbt option that works with `dbt run` will also work with `lightdash dbt run`. That includes all the [Lightdash dbt options](#dbt-options), and more ([see dbt run docs](https://docs.getdbt.com/reference/commands/run)).
 
+
 **Options:**
 
 - `--exclude-meta`
@@ -440,14 +449,16 @@ Any dbt option that works with `dbt run` will also work with `lightdash dbt run`
 - `-no` or `--assume-no`
   - assume no to prompts (default: false)
 
-**Examples:**
+
+**Example:**
 
 Run a single model and create or update its `schema.yml` file:
 
 ```bash
 lightdash dbt run --select mymodel
 ```
 
+
 ### `lightdash download`
 
 Downloads all charts and dashboards from your Lightdash project as code. A `lightdash` directory is created in your working directory and all of the charts and dashboards are written there as .yml files.
@@ -456,6 +467,7 @@ E.g. if you're running this command inside your dbt directory (eg: `/home/javi/d
 
 You can make changes to the code and upload these changes back to your Lightdash project. Content that's been downloaded as code can still be managed in the Lightdash UI.
 
+
 **Options:**
 
 - `--charts` or `-c`
@@ -467,6 +479,7 @@ You can make changes to the code and upload these changes back to your Lightdash
 - `--project <project uuid>`
   - download all charts and dashboards from a specific project. You can find the project UUID for a project from a Lightdash URL. E.g. here, the project UUID is `123-project-uuid` `https://app.lightdash.cloud/projects/123-project-uuid/`
 
+
 **Examples:**
 
 Download all charts and dashboards from your project.
@@ -478,7 +491,7 @@ lightdash download
 Download a specific dashboard from your Lightdash project.
 
 ```bash
-lightdash upload -d https://app.lightdash.cloud/my-dashboard-url
+lightdash download -d https://app.lightdash.cloud/my-dashboard-url
 ```
 
 Download all content from a project to the directory `/Users/katiehindson/lightdash/lightdash-analytics/`
@@ -507,6 +520,7 @@ Uploads charts and dashboards that you've made changes to from the `lightdash/`
 
 If there have been changes made to a chart or dashboard in the application that is being uploaded from code, `lightdash upload` will overwrite the changes.
 
+
 **Options:**
 
 - `--force`
@@ -520,6 +534,7 @@ If there have been changes made to a chart or dashboard in the application that
 - `--project <project uuid>`
   - upload all charts and dashboards from a specific project. You can find the project UUID for a project from a Lightdash URL. E.g. here, the project UUID is `123-project-uuid` `https://app.lightdash.cloud/projects/123-project-uuid/`
 
+
 **Examples:**
 
 Upload all charts and dashboards in code from your `lightdash/` directory to your Lightdash project.
@@ -554,6 +569,60 @@ Upload all charts and dashboards from your `lightdash/` directory to a specific
 lightdash upload --project 21eef0b9-5bae-40f3-851e-9554588e71a6
 ```
 
+
+### `lightdash rename`
+
+Rename model or field names across all content in your Lightdash project. This command will do a full find and replace on a field or table so all references in chart fields, dashboard filters, table calculations, custom metrics, etc. can be changed at once. 
+
+
+**Arguments:**
+
+- `--type`
+  - Specify what you're renaming
+  - Accepted values: `field` or `model`
+- `--from`
+  - The current name of the table or field you want to change (this is the slug from your YAML definition, i.e. `num_users`)
+- `--to`
+  - The new name you want to use (must match the new slug in your YAML for this field or table, i.e. `count_distinct_user_id`)
+
+
+**Options:**
+
+- `--project`, `-p`
+  - Project UUID to target a specific project. 
+  - (default: The most recent project you set with `lightdash config set-project`)
+- `--model`, `-m`
+  - The model to target for field renaming. This is only needed if the current field name is not unique in your project.
+- `--dry-run`
+  - List all content the rename action will change, no changes will be made. 
+- `--list`
+  - List all charts and dashboards that were renamed after the command is complete.
+- `--assume-yes`, `-y`
+  - Assume yes to all prompts.
+
+
+**Examples:**
+
+Rename the field `num_users` to `count_distinct_user_id`. 
+
+```bash
+lightdash rename --type field --from num_users --to count_distinct_user_id
+```
+
+Do a dry run of changing the table reference from `users_mart_v1` to `users`.
+
+```bash
+lightdash rename --type model --from users_mart_v1 --to users --dry-run
+```
+
+Rename the field `count` to `count_distinct_order_id` in the `orders` model and list all affected content when complete:
+
+```bash
+lightdash rename --type field --model orders --from count --to count_distinct_order_id --list
+```
+
+---
+
 ## dbt options
 
 These are options from the dbt Core CLI that also work with some Lightdash CLI commands.