Metadata Operations

PCLI2 provides comprehensive metadata operations for managing asset metadata including creating, retrieving, updating, and deleting asset metadata.

Overview

Metadata is essential for organizing and searching your assets effectively. PCLI2 supports comprehensive metadata operations to help you manage your asset metadata efficiently.

Metadata Operations

PCLI2 provides several commands for working with asset metadata:

1. Create/Update Individual Asset Metadata

Add or update a single metadata field on an asset:

# Add or update a single metadata field on an asset
pcli2 asset metadata create --path "/Home/Folder/Model.stl" --name "Material" --value "Steel" --type "text"

# Add or update a single metadata field on an asset by UUID
pcli2 asset metadata create --uuid "123e4567-e89b-12d3-a456-426614174000" --name "Weight" --value "15.5" --type "number"

2. Retrieve Asset Metadata

Get all metadata for an asset:

# Get all metadata for an asset in JSON format (default)
pcli2 asset metadata get --path "/Home/Folder/Model.stl"

# Get all metadata for an asset in CSV format (suitable for batch operations)
pcli2 asset metadata get --uuid "123e4567-e89b-12d3-a456-426614174000" --format csv

3. Delete Asset Metadata

Delete specific metadata fields from an asset:

# Delete specific metadata fields from an asset
pcli2 asset metadata delete --path "/Home/Folder/Model.stl" --name "Material" --name "Weight"

# Delete metadata fields using comma-separated list
pcli2 asset metadata delete --uuid "123e4567-e89b-12d3-a456-426614174000" --name "Material,Weight,Description"

The delete command now uses the dedicated API endpoint to properly remove metadata fields from assets, rather than fetching all metadata and re-updating the asset without the specified fields. This provides more efficient and accurate metadata deletion.

4. Create/Update Metadata for Multiple Assets

Create or update metadata for multiple assets from a CSV file:

# Create or update metadata for multiple assets from a CSV file
pcli2 asset metadata create-batch --input "metadata.csv"

CSV Formats for Batch Metadata Operations

The create-batch command accepts two CSV layouts. The layout is detected automatically from the header row: if any column name starts with metadata:, the file is treated as the UI (horizontal) format; otherwise it is treated as the classic (vertical) format. You can also force a layout explicitly with --csv-format classic or --csv-format ui (the default is --csv-format auto).

In both layouts, empty values are skipped by default: the existing metadata field on the asset, if any, is left untouched, so a sparse file can be used to incrementally add or update fields. Pass --delete-if-empty to instead delete a metadata field from the asset when the file contains an empty value for it — useful when replacing an asset's metadata wholesale.

Classic (Vertical) Format

The classic CSV format used by asset metadata get --format csv and asset metadata create-batch --input is designed for seamless round-trip operations:

ASSET_PATH,NAME,VALUE,TYPE
/Home/Folder/Model1.stl,Material,Steel,text
/Home/Folder/Model1.stl,Weight,15.5,number
/Home/Folder/Model2.ipt,Inventory Qty,42,number
/Home/Folder/Model2.ipt,Supplier Link,https://example.com/,url
/Home/Folder/Model2.ipt,Exportable,true,boolean

The CSV format specifications:

  • Header Row: Must contain ASSET_PATH,NAME,VALUE in that order, optionally followed by TYPE
  • ASSET_PATH: Path to the asset in Physna (e.g., /Home/Folder/Model.stl). A leading /Home — the name Physna shows for the root folder — is treated as the root, so /Home/NX/part.prt, /NX/part.prt, and NX/part.prt all refer to the same asset
  • NAME: Name of the metadata field to set
  • VALUE: Value to assign to the metadata field. Values are automatically coerced to the field's type (see Metadata Field Types). An empty value is skipped by default, or deletes the field from the asset when --delete-if-empty is passed
  • TYPE (optional): One of text (default), number, boolean, or url. This only governs the type used when registering a new field; for a field that already exists in Physna, the existing registered type is authoritative and the TYPE column is ignored. The column is optional per row — some rows may include it and others may omit it
  • File Encoding: Must be UTF-8 encoded
  • Quoting: Values containing commas, quotes, or newlines must be enclosed in double quotes
  • Escaping: Double quotes within values must be escaped by doubling them (e.g., "15.5"" diameter")
  • Empty Rows: Will be ignored during processing
  • Multiple Fields: If an asset has multiple metadata fields to update, include multiple rows with the same ASSET_PATH but different NAME and VALUE combinations

Example Command:

# Create/update metadata for multiple assets from a CSV file
pcli2 asset metadata create-batch --input "metadata.csv"

Deleting metadata fields via CSV:

Pass --delete-if-empty and leave the VALUE column empty to remove a metadata field from an asset:

ASSET_PATH,NAME,VALUE
/Home/Folder/Model1.stl,ObsoleteField,
/Home/Folder/Model1.stl,Material,Steel

pcli2 asset metadata create-batch --input "metadata.csv" --delete-if-empty

In the example above, ObsoleteField is deleted and Material is set to Steel in a single pass. Without --delete-if-empty, the ObsoleteField row would be skipped with a warning and only Material would be updated.

Note: The create-batch command groups all rows by asset path, then issues deletes (empty values, when --delete-if-empty is passed) followed by updates (non-empty values) per asset in one batch. Multiple rows with the same ASSET_PATH are combined into a single API interaction.

UI (Horizontal) Format

The Physna web UI's bulk metadata upload uses a horizontal layout with one row per asset and one column per metadata field. create-batch accepts these files directly:

"path","id","metadata:Material","metadata:Color","metadata:Weight"
"/domain/assets/part1.sldprt","123e4567-e89b-12d3-a456-426614174000","Steel","Blue","2.5kg"
"/domain/assets/part2.step","","Aluminum","Red","1.2kg"
"/domain/assets/assembly.sldasm","","Mixed","",""

The UI format specifications:

  • path: Full path to the asset in Physna
  • id: Optional asset UUID. When present and non-empty, it takes precedence over the path and is used directly, without path resolution. An invalid UUID is an error (there is no fallback to the path, since that could silently target a different asset)
  • metadata:<field name>: One column per metadata field. The metadata: prefix is stripped to obtain the field name
  • Empty metadata cells: Skipped by default — the existing field value on the asset, if any, is left untouched. With --delete-if-empty, an empty cell deletes the field from the asset instead
  • Other columns: Any column that is not path, id, or metadata:* is ignored, with a warning listing the ignored columns
  • Row identification: Each row must provide a UUID or a path; a row with neither is an error

The whole file is parsed and validated before any API call is made, so a malformed file (e.g. an invalid UUID) fails fast with a line-numbered error instead of half-applying.

# Auto-detected from the header row
pcli2 asset metadata create-batch --input "ui-export.csv"

# Or forced explicitly
pcli2 asset metadata create-batch --input "ui-export.csv" --csv-format ui

Listing a Tenant's Registered Metadata Fields

Metadata fields are registered per tenant, each with a name and a type. Use tenant metadata list to see every field currently registered in the active tenant:

# JSON (default)
pcli2 tenant metadata list

# CSV, ready to turn into a create-batch file
pcli2 tenant metadata list --format csv --headers

The CSV output uses the same column headers as the classic create-batch input (ASSET_PATH,NAME,VALUE,TYPE), with NAME and TYPE filled from the registry and ASSET_PATH and VALUE left blank:

ASSET_PATH,NAME,VALUE,TYPE
,Description,,text
,Exportable,,boolean
,Inventory Qty,,number
,Supplier Link,,url
,Unit Price ($),,number

This makes it easy to build a batch-upload template: save the listing, then for each asset fill in ASSET_PATH and VALUE (replicating the field rows per asset). Because values are coerced to each field's registered type, you do not need to touch the TYPE column for fields that already exist.

# Save the field list as a starting template
pcli2 tenant metadata list --format csv --headers > fields.csv

Advanced Metadata Workflow: Export, Modify, Reimport

One of the most powerful features of PCLI2 is the ability to export metadata, modify it externally, and reimport it:

  1. Export Metadata:

    # Export all metadata for an asset to a CSV file
pcli2 asset metadata get --path "/Home/Folder/Model.stl" --format csv > model_metadata.csv

# Export metadata for multiple assets in a folder
pcli2 asset list --folder-path "/Home/Folder/" --metadata --format csv > folder_metadata.csv

  2. Modify Metadata Externally:

    • Open the CSV file in a spreadsheet application (Excel, Google Sheets, etc.)
    • Make the desired changes to metadata values
    • To delete a field, clear its VALUE cell (leave it blank) and reimport with --delete-if-empty
    • Save the file in CSV format

  3. Reimport Modified Metadata:

    # Update assets with modified metadata (blank values are skipped)
pcli2 asset metadata create-batch --input "modified_metadata.csv"

# Or replace metadata wholesale: blank values delete the field from the asset
pcli2 asset metadata create-batch --input "modified_metadata.csv" --delete-if-empty

This workflow enables powerful bulk metadata operations while maintaining the flexibility to use familiar spreadsheet tools for data manipulation.

Metadata Field Types

PCLI2 supports four metadata field types:

  1. Text (default): String values

    pcli2 asset metadata create --path "/Home/Model.stl" --name "Description" --value "Sample part description" --type "text"

  2. Number: Numeric values

    pcli2 asset metadata create --path "/Home/Model.stl" --name "Weight" --value "15.5" --type "number"

  3. Boolean: True/False values

    pcli2 asset metadata create --path "/Home/Model.stl" --name "Approved" --value "true" --type "boolean"

  4. URL: Link values (stored as a string)

    pcli2 asset metadata create --path "/Home/Model.stl" --name "Supplier Link" --value "https://example.com/" --type "url"

Automatic type coercion

Every metadata field in a tenant is registered with a type, and the Physna API rejects a value whose JSON type does not match. Because a CSV cell is just text, PCLI2 coerces each value to the field's registered type before sending it — so create-batch works against typed fields without you having to declare anything:

  • A number field receives 18 (a JSON number) rather than the string "18"; 84.50 is sent as 84.5
  • A boolean field accepts true/false, 1/0, yes/no, on/off (case-insensitive)
  • text and url fields store the value as a string

If a value cannot be represented as the field's type — for example the text N/A for a number field — that row is a type conflict and is reported as an error (see create-batch Error Behavior).

The registered type always wins. The --type flag (single create) and the TYPE column (batch) only decide the type used when a field is registered for the first time; they cannot change the type of an existing field. To change a field's type, delete and recreate it.

Best Practices

  1. Use Descriptive Names: Choose clear, consistent names for metadata fields across your organization
  2. Validate Data Types: Ensure values match the expected data type for each field
  3. Batch Operations: Use CSV batch operations for large-scale metadata updates
  4. Backup Before Bulk Operations: Export metadata before performing bulk deletions
  5. Test First: Use small test sets before applying operations to large asset collections
  6. Use Proper Authentication: Ensure your credentials have appropriate permissions for metadata operations

Error Handling

Metadata operations provide detailed error messages, retry transient network failures internally, and validate input formats before processing.

create-batch Error Behavior

By default, asset metadata create-batch stops on the first error and prints a summary of how many assets were processed successfully. This makes failures visible instead of letting a batch silently complete with partial results.

Specifically:

  • CSV parsing errors: always terminate immediately — the input file is expected to be well-formed
  • Unresolvable asset paths (asset not found): by default, terminates the batch. Pass --continue-on-error to skip the failing asset and continue with the remaining rows
  • Metadata update/delete failures, including type conflicts (a value that cannot be represented as the field's registered type): by default, terminate the batch. Pass --continue-on-error to skip the offending asset and continue with the remaining rows
  • Authentication failures: always terminate with a remediation message directing the user to re-authenticate, regardless of --continue-on-error

With --continue-on-error, skipped assets are reported with a concise warning as they are encountered, and the final summary reports how many assets succeeded and how many failed.

Example — skip both unresolvable paths and conflicting values:

pcli2 asset metadata create-batch --input "metadata.csv" --continue-on-error

On completion (or termination), a summary is printed to stderr showing the number of successful and failed assets.

Performance Considerations

Large-Scale Operations

For bulk metadata operations:

# Process during off-peak hours
pcli2 asset metadata create-batch --input "large_metadata.csv"

Monitoring Progress

Monitor progress during long-running operations:

# Show progress during batch operations
pcli2 asset metadata create-batch --input "metadata.csv" --progress

Integration with Other Commands

Metadata operations work seamlessly with other PCLI2 commands:

# Chain with asset operations
pcli2 asset list --folder-path "/Home/Parts/" --format csv | \
pcli2 asset metadata create-batch --input "metadata_updates.csv"

# Export results for auditing
pcli2 asset metadata get --path "/Home/Parts/Model.stl" --format csv > metadata_export.csv

Limitations

  1. API Rate Limits: Extensive operations may be rate-limited by the Physna API
  2. Processing Time: Large batch operations can take considerable time
  3. Metadata Types: Supports text, number, boolean, and url metadata fields
  4. Asset Access: Can only process assets accessible to your authenticated user
  5. Field Names: Metadata field names must be unique per asset and follow Physna naming conventions

Always test operations on a small scale before running them on large datasets.