hana-cli

# massConvert > Command: `massConvert` > Category: **Mass Operations** > Status: Production Ready ## Description Convert a group of tables and views to CDS or HDBTable format. This command generates CAP CDS definitions or native HANA HDI artifacts from existing database tables and views, enabling migration from classic database schemas to modern HDI-based development. ### Use Cases - **Schema Migration**: Convert existing tables to HDI artifacts for cloud-native deployment - **CAP Development**: Generate CDS models from legacy database structures - **Documentation**: Create declarative definitions of existing schemas - **Multi-Target**: Export to both CDS and HDI formats for different deployment targets - **Bulk Conversion**: Process entire schemas or filtered object sets at once ### Output Formats | Format | Description | Best For | |----------------------|------------------------------------------------------|-----------------------------| | `cds` | CAP CDS format with type definitions | CAP/Node.js projects | | `hdbtable` | Native HANA HDI table definitions | Pure HDI projects | | `hdbmigrationtable` | HDI migration table format (preserves data) | Migrating existing data | ### Key Features - **Wildcard Support**: Use patterns to select multiple tables/views - **Type Mapping**: Automatic conversion between database and CDS types - **Namespace Support**: Generate CDS with proper namespace structure - **Path Handling**: Flexible options for handling dotted paths and colons - **Synonym Generation**: Optional creation of synonym definitions - **Progress Logging**: Continuous logging for large conversion operations ## Syntax ```bash hana-cli massConvert [schema] [table] [view] [options] ``` ## Aliases - `mc` - `massconvert` - `massConv` - `massconv` ## Command Diagram ```mermaid graph TD Start([hana-cli massConvert]) --> Input{Input Selection} Input -->|schema| Schema[Schema Name Default: CURRENT_SCHEMA] Input -->|table| Table[Table Pattern Default: * all tables] Input -->|view| View[View Pattern Optional] Schema --> Limit[Apply Limit Default: 200 objects] Table --> Limit View --> Limit Limit --> Format{Output Format} Format -->|output=cds| CDS[📄 CAP CDS Format Default] Format -->|output=hdbtable| HDBTable[📄 HDI Table Format] Format -->|output=hdbmigrationtable| Migration[📄 HDI Migration Format Preserves data] CDS --> TypeOptions{Type Configuration} HDBTable --> TypeOptions Migration --> TypeOptions TypeOptions -->|useHanaTypes=false| StdTypes[Standard CDS Types Default] TypeOptions -->|useHanaTypes=true| HanaTypes[HANA-Specific Types e.g., ST_POINT, ST_GEOMETRY] StdTypes --> Catalog{Catalog Mode} HanaTypes --> Catalog Catalog -->|useCatalogPure=false| Standard[Standard Definitions Default] Catalog -->|useCatalogPure=true| Pure[Pure Catalog With associations & merge] Standard --> Naming{Naming Options} Pure --> Naming Naming -->|useQuoted=false| Unquoted[Unquoted Identifiers Default] Naming -->|useQuoted=true| Quoted[Quoted Identifiers For special chars] Unquoted --> PathHandling{Path Handling} Quoted --> PathHandling PathHandling -->|keepPath=false| NormalPath[Standard Path Default] PathHandling -->|keepPath=true| KeepDots[Keep Dots in Path] PathHandling -->|noColons=true| ReplaceColons[Replace :: with .] NormalPath --> Namespace{Namespace} KeepDots --> Namespace ReplaceColons --> Namespace Namespace -->|namespace specified| WithNS[Apply CDS Namespace] Namespace -->|no namespace| NoNS[No Namespace] WithNS --> Output{Output Options} NoNS --> Output Output -->|folder| TargetFolder[Output Folder Default: ./] Output -->|filename| SingleFile[Single Output File] Output -->|synonyms| SynFile[Generate Synonyms File] TargetFolder --> Logging{Error Handling} SingleFile --> Logging SynFile --> Logging Logging -->|log=false| StopError[Stop on First Error Default] Logging -->|log=true| ContinueLog[Continue & Log Write to file] StopError --> Generate[Generate Files] ContinueLog --> Generate Generate --> Complete([✅ Conversion Complete Files Created]) style Start fill:#0092d1 style Complete fill:#2ecc71 style Format fill:#f39c12 style TypeOptions fill:#f39c12 style Output fill:#9b59b6 ``` ## Parameters ### Positional Arguments | Parameter | Type | Description | |-----------|--------|-------------------------------------------------------------| | `schema` | string | Schema name to process (default: current schema) | | `table` | string | Database table pattern (supports wildcards, default: `*`) | | `view` | string | Database view pattern (supports wildcards, optional) | ### Options #### Source Selection | Option | Alias | Type | Default | Description | |-------------|-------|--------|----------------------|------------------------------------------------------| | `--schema` | `-s` | string | `**CURRENT_SCHEMA**` | Schema name containing tables/views to convert | | `--table` | `-t` | string | `*` | Table name pattern (supports SQL wildcards) | | `--view` | `-v` | string | - | View name pattern (supports SQL wildcards) | | `--limit` | `-l` | number | `200` | Maximum number of objects to convert | #### Output Configuration | Option | Alias | Type | Default | Description | |--------------|-------|---------|---------|---------------------------------------------------------------------------------| | `--output` | `-o` | string | `cds` | Output format. Choices: `cds`, `hdbtable`, `hdbmigrationtable` | | `--folder` | `-f` | string | `./` | Output folder for generated files | | `--filename` | `-n` | string | - | Output file name (single file). If not specified, creates one file per object | | `--namespace`| `-ns` | string | `""` | CDS namespace for generated definitions | | `--synonyms` | - | string | `""` | Synonyms output file name (generates synonym definitions) | | `--log` | - | boolean | `false` | Write progress log to file instead of stopping on first error | #### Type & Format Options | Option | Alias | Type | Default | Description | |--------------------|-----------------------------|---------|---------|----------------------------------------------------------------------------------------| | `--useHanaTypes` | `--hana` | boolean | `false` | Use HANA-specific data types (ST_POINT, ST_GEOMETRY, etc.) | | `--useCatalogPure` | `--catalog`, `--pure` | boolean | `false` | Use pure catalog definitions with associations and merge settings | | `--useExists` | `--exists`, `--persistence` | boolean | `true` | Use persistence exists annotation in CDS | | `--useQuoted` | `-q`, `--quoted` | boolean | `false` | Use quoted identifiers for non-standard names | #### Path & Naming Options | Option | Alias | Type | Default | Description | |--------------|-------|---------|---------|------------------------------------------------------| | `--keepPath` | - | boolean | `false` | Keep table/view path with dots | | `--noColons` | - | boolean | `false` | Replace `::` in table/view path with `.` | ### Connection Parameters | Option | Alias | Type | Default | Description | |-----------|-------|---------|---------|------------------------------------------------------| | `--admin` | `-a` | boolean | `false` | Connect via admin (default-env-admin.json) | | `--conn` | - | string | - | Connection filename to override default-env.json | ### Troubleshooting | Option | Alias | Type | Default | Description | |---------------------|-----------|---------|---------|----------------------------------------------------------------------------------------------------------| | `--disableVerbose` | `--quiet` | boolean | `false` | Disable verbose output - removes all extra output that is only helpful to human readable interface | | `--debug` | `-d` | boolean | `false` | Debug hana-cli itself by adding output of LOTS of intermediate details | For a complete list of parameters and options, use: ```bash hana-cli massConvert --help ``` ## Examples ### Convert All Tables to CDS ```bash hana-cli massConvert --schema MYSCHEMA --output cds ``` ### Convert with Namespace and HDI Format ```bash hana-cli massConvert --schema MYSCHEMA --table % --output hdbtable --namespace my.app --folder db/src/ ``` ### Convert Tables to CDS with Type Preservation ```bash hana-cli massConvert --schema MYSCHEMA --table "%" --output cds --useHanaTypes --useCatalogPure ``` ### Convert Specific Tables with Limit ```bash hana-cli massConvert -s MYSCHEMA -t "CUSTOMER%" -o cds -ns myapp --limit 10 ``` Convert tables in MYSCHEMA to CAP CDS format in the current directory. ### Convert Specific Tables to HDI Format ```bash hana-cli massConvert --schema MYSCHEMA --table "SALES_%" --output hdbtable ``` Convert all tables starting with `SALES_` to HDI table definitions. ### Convert with Namespace ```bash hana-cli massConvert --schema MYSCHEMA --namespace "com.company.sales" --output cds ``` Generate CDS definitions with a proper namespace structure. ### Convert to Single File ```bash hana-cli massConvert --schema MYSCHEMA --filename schema.cds ``` Output all table definitions to a single `schema.cds` file. ### Convert with HANA-Specific Types ```bash hana-cli massConvert --schema GIS_DATA --useHanaTypes --output cds ``` Convert spatial/geometric tables preserving HANA-specific types like ST_POINT. ### Migration Table Format (Preserve Data) ```bash hana-cli massConvert --schema LEGACY --output hdbmigrationtable --folder ./migration ``` Generate HDI migration tables that preserve existing data during deployment. ### Convert with Quoted Identifiers ```bash hana-cli massConvert --schema MYSCHEMA --table "Special-Name%" --useQuoted ``` Convert tables with special characters in names using quoted identifiers. ### Generate with Synonyms ```bash hana-cli massConvert --schema MYSCHEMA --synonyms synonyms.hdbsynonym ``` Convert tables and generate corresponding synonym definitions. ### Large Schema with Logging ```bash hana-cli massConvert --schema BIGSCHEMA --limit 500 --log --folder ./converted ``` Convert up to 500 objects, continuing on errors and logging progress to file. ### Pure Catalog Mode ```bash hana-cli massConvert --schema MYSCHEMA --useCatalogPure --output cds ``` Generate pure catalog definitions including associations and merge settings. ## Advanced Usage ### Pattern Matching Use SQL wildcards for selective conversion: ```bash # Convert all tables starting with TEMP_ hana-cli massConvert --table "TEMP_%" # Convert both tables and views matching pattern hana-cli massConvert --table "DATA_%" --view "V_DATA_%" # Convert tables ending with _LOG hana-cli massConvert --table "%_LOG" ``` ### Handling Special Paths ```bash # Keep original dotted paths hana-cli massConvert --keepPath # Replace :: with . in paths hana-cli massConvert --noColons # Use quoted identifiers for compatibility hana-cli massConvert --useQuoted ``` ### Custom Output Organization ```bash # Output to specific folder structure hana-cli massConvert --folder ./db/src/tables --output hdbtable # Single file with namespace hana-cli massConvert --filename all-entities.cds --namespace app.entities ``` ## Output Examples ### CDS Output Format ```cds namespace com.example.sales; entity CUSTOMERS { key CUSTOMER_ID : Integer; NAME : String(100); EMAIL : String(255); CREATED_AT : Timestamp; } entity ORDERS { key ORDER_ID : Integer; CUSTOMER_ID : Integer; ORDER_DATE : Date; TOTAL_AMOUNT : Decimal(15,2); } ``` ### HDI Table Output Format ```sql COLUMN TABLE "CUSTOMERS" ( "CUSTOMER_ID" INTEGER NOT NULL, "NAME" NVARCHAR(100), "EMAIL" NVARCHAR(255), "CREATED_AT" TIMESTAMP, PRIMARY KEY ("CUSTOMER_ID") ) ``` ### Progress Output ```text Converting Tables to cds: ✓ CUSTOMERS ✓ ORDERS ✓ PRODUCTS ✓ INVOICES Successfully converted 4 tables to ./db/src/ ``` ## Best Practices ### 1. Start with a Test Schema ```bash # Test conversion on a small subset first hana-cli massConvert --schema TEST_SCHEMA --limit 10 ``` ### 2. Use Namespaces for CDS ```bash # Always use namespaces for organized CDS models hana-cli massConvert --namespace "app.db.tables" ``` ### 3. Choose the Right Output Format - **CDS**: For CAP applications and cross-database portability - **HDI Table**: For pure HANA HDI deployments - **HDI Migration**: When preserving existing data is critical ### 4. Handle Large Schemas Carefully ```bash # Use limits and logging for large conversions hana-cli massConvert --limit 200 --log --folder ./batch1 ``` ### 5. Review Generated Files Always review generated definitions before deployment: - Check type mappings are appropriate - Verify constraints and keys are preserved - Test in development before production ## Type Mapping ### Standard vs HANA-Specific Types | Database Type | Standard CDS (`useHanaTypes=false`) | HANA-Specific (`useHanaTypes=true`) | |---------------|-------------------------------------|-------------------------------------| | ST_POINT | Binary | hana.ST_POINT | | ST_GEOMETRY | Binary | hana.ST_GEOMETRY | | NVARCHAR | String | String | | DECIMAL | Decimal | Decimal | | TIMESTAMP | Timestamp | Timestamp | Use `--useHanaTypes` when: - Working with spatial/geometric data - Using HANA-specific features - Not planning cross-database deployment ## Common Issues & Solutions **Issue**: Too many objects to convert ```bash # Solution: Use limit or pattern matching hana-cli massConvert --limit 100 hana-cli massConvert --table "ACTIVE_%" ``` **Issue**: Special characters in table names ```bash # Solution: Use quoted identifiers hana-cli massConvert --useQuoted ``` **Issue**: Conversion errors stopping process ```bash # Solution: Enable logging to continue hana-cli massConvert --log ``` **Issue**: Need to preserve associations ```bash # Solution: Use pure catalog mode hana-cli massConvert --useCatalogPure ``` --- ## massConvertUI (UI Variant) > Command: `massConvertUI` > Status: Production Ready **Description:** Convert a group of tables to CDS or HDBTable format via browser-based UI **Syntax:** ```bash hana-cli massConvertUI [schema] [table] [options] ``` **Aliases:** - `mcui` - `massconvertui` - `massConvUI` - `massconvui` **Parameters:** All `massConvert` options apply, plus: | Option | Alias | Type | Default | Description | |--------------|-------|---------|---------|----------------------------------------------| | `--port` | `-p` | integer | `3010` | Port to run the HTTP server for the UI | **Example Usage:** ```bash # Launch UI on default port hana-cli massConvertUI # Launch UI on custom port hana-cli massConvertUI --port 8080 # Pre-select schema in UI hana-cli massConvertUI --schema MYSCHEMA ``` The browser-based UI provides: - Interactive schema and object selection - Real-time preview of conversion options - Visual feedback during conversion process - Download converted files directly from browser ## Related Commands - [massDelete](mass-delete.md) - Bulk delete database objects - [massExport](mass-export.md) - Export database objects in various formats - [massRename](mass-rename.md) - Rename fields in CDS-based export files - [massUpdate](mass-update.md) - Bulk update database records - [cds](../developer-tools/cds.md) - Display database objects via CDS - [createModule](../developer-tools/create-module.md) - Create new DB module structure See the [Commands Reference](../all-commands.md) for other commands in this category. ## See Also - [Category: Mass Operations](..) - [All Commands A-Z](../all-commands.md)