تحرير

مشاركة عبر

update command

Update an existing entity definition in the Data API builder configuration file. Use this command to adjust source metadata, permissions, exposure (REST/GraphQL), policies, caching, relationships, mappings, and descriptive metadata after the entity has already been added.

Tip

Use dab add to create new entities, and dab update to evolve them. Field name remapping (--map) is only available in update, not in add.

Syntax

dab update <entity-name> [options]

Quick glance

Option Summary
<entity-name> Required positional argument. Logical entity name.
-s, --source Name of the source table, view, or stored procedure.
--permissions Role and actions in role:actions format.
--description Replace entity description.
-c, --config Path to config file. Default resolution applies if omitted.
--help Display the help screen.
--version Display version information.

Cache

Option Summary
--cache.enabled Enable or disable entity caching.
--cache.ttl Cache time-to-live in seconds.

Fields

Option Summary
--fields.exclude Comma-separated list of excluded fields.
--fields.include Comma-separated list of included fields (* = all).
-m, --map Field mapping pairs name:alias. Replaces entire set.

Fields metadata

Option Summary
--fields.name Name of the database column to describe.
--fields.alias Alias for the field.
--fields.description Description for the field.
--fields.primary-key Set this field as a primary key.

GraphQL

Option Summary
--graphql GraphQL exposure: false, true, singular, or singular:plural.
--graphql.operation Stored procedures only: query or mutation (default mutation).

Permissions & Policies

Option Summary
--permissions role:actions for a single role. Run multiple times for multiple roles.
--policy-database OData-style filter injected in DB query.
--policy-request Pre-database request filter.

Relationships

Option Summary
--relationship Relationship name. Use with relationship options.
--cardinality Relationship cardinality: one or many.
--target.entity Target entity name.
--linking.object Linking object for many-to-many.
--linking.source.fields Linking object fields pointing to source.
--linking.target.fields Linking object fields pointing to target.
--relationship.fields Field mappings for direct relationships.

REST

Option Summary
--rest REST exposure: false, true, or custom path.
--rest.methods Stored procedures only. Replace allowed HTTP verbs.

Source

Option Summary
-s, --source Underlying database object name.
--source.key-fields Required for views or non-PK tables.
--source.params Stored procedures only. Replace default params.
--source.type Source type: table, view, or stored-procedure.

Parameters (stored procedures)

Option Summary
--parameters.name Comma-separated list of parameter names.
--parameters.description Comma-separated list of parameter descriptions.
--parameters.required Comma-separated list of required flags.
--parameters.default Comma-separated list of default values.

--cache.enabled

Enable or disable caching for this entity.

Example

dab update \
  Book \
  --cache.enabled true

Resulting config

{
  "entities": {
    "Book": {
      "cache": {
        "enabled": true
      }
    }
  }
}

--cache.ttl

Set cache time-to-live in seconds. Only effective if caching is enabled.

Example

dab update \
  Book \
  --cache.ttl 600

Resulting config

{
  "entities": {
    "Book": {
      "cache": {
        "ttl-seconds": 600
      }
    }
  }
}

Note

Supplying TTL when cache is disabled has no effect until caching is enabled.

--description

Replace entity description.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  Book \
  --description "Updated description"

Resulting config

{
  "entities": {
    "Book": {
      "description": "Updated description"
    }
  }
}

--fields.exclude

Comma-separated list of fields to exclude.

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --fields.exclude "internal_flag,secret_note"

Resulting config

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "exclude": [ "internal_flag", "secret_note" ]
              }
            }
          ]
        }
      ]
    }
  }
}

--fields.include

Comma-separated list of fields to include. * includes all fields. Replaces existing include list.

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --fields.include "id,title,author"

Resulting config

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "fields": {
                "exclude": [],
                "include": [ "id", "title", "author" ]
              }
            }
          ]
        }
      ]
    }
  }
}

--graphql

Control GraphQL exposure.

Example

dab update \
  Book \
  --graphql book:books

Resulting config

{
  "entities": {
    "Book": {
      "graphql": {
        "enabled": true,
        "type": {
          "singular": "book",
          "plural": "books"
        }
      }
    }
  }
}

--graphql.operation

Stored procedures only. Sets operation type. Default is mutation.

Example

dab update \
  RunReport \
  --graphql.operation query

Resulting config

{
  "entities": {
    "RunReport": {
      "graphql": {
        "operation": "query"
      }
    }
  }
}

Note

Supplying --graphql.operation for tables or views is ignored.

-m, --map

Map database fields to exposed names. Replaces the entire mapping set.

Example

dab update \
  Book \
  --map "id:bookId,title:bookTitle"

Resulting config

{
  "entities": {
    "Book": {
      "fields": [
        {
          "name": "id",
          "alias": "bookId",
          "primary-key": false
        },
        {
          "name": "title",
          "alias": "bookTitle",
          "primary-key": false
        }
      ]
    }
  }
}

Important

Any existing mappings are overwritten. Restate all mappings you want to keep.

--permissions

Adds or updates permissions for a single role and its actions.

You can run dab update multiple times (once per role) to add multiple roles.

Example

dab update \
  Book \
  --permissions "anonymous:read"

dab update \
  Book \
  --permissions "authenticated:create,read,update"

Resulting config

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read"
            }
          ]
        },
        {
          "role": "authenticated",
          "actions": [
            { "action": "create" },
            { "action": "read" },
            { "action": "update" }
          ]
        }
      ]
    }
  }
}

Note

If the specified role already exists, its actions are updated; otherwise, the role is added.

--policy-database

OData-style filter appended to DB query.

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --policy-database "region eq 'US'"

Resulting config

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "database": "region eq 'US'"
              }
            }
          ]
        }
      ]
    }
  }
}

--policy-request

Request-level policy evaluated before hitting the database.

Example

dab update \
  Book \
  --permissions "anonymous:read" \
  --policy-request "@claims.role == 'admin'"

Resulting config

{
  "entities": {
    "Book": {
      "permissions": [
        {
          "role": "anonymous",
          "actions": [
            {
              "action": "read",
              "policy": {
                "request": "@claims.role == 'admin'"
              }
            }
          ]
        }
      ]
    }
  }
}

--relationship

Define or update a relationship. Use with other relationship options.

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Resulting config

{
  "entities": {
    "User": {
      "relationships": {
        "profile": {
          "cardinality": "one",
          "target.entity": "Profile",
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    }
  }
}

--cardinality

Cardinality for the relationship. Use with --relationship.

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

--target.entity

Target entity name for the relationship. Use with --relationship.

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

--linking.object

Many-to-many only. Database object name used as the linking object.

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--linking.source.fields

Many-to-many only. Comma-separated list of linking object fields pointing to the source entity.

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--linking.target.fields

Many-to-many only. Comma-separated list of linking object fields pointing to the target entity.

Example

dab update \
  Book \
  --relationship books_authors \
  --target.entity Author \
  --cardinality many \
  --relationship.fields "id:id" \
  --linking.object dbo.books_authors \
  --linking.source.fields book_id \
  --linking.target.fields author_id

--relationship.fields

Colon-separated field mappings for direct relationships.

The --relationship.fields value is a comma-separated list of sourceField:targetField pairs.

Example

dab update \
  User \
  --relationship profile \
  --target.entity Profile \
  --cardinality one \
  --relationship.fields "id:user_id"

Resulting config

{
  "entities": {
    "User": {
      "relationships": {
        "profile": {
          "source.fields": [ "id" ],
          "target.fields": [ "user_id" ]
        }
      }
    }
  }
}

--rest

Control REST exposure.

Example

dab update \
  Book \
  --rest BooksApi

Resulting config

{
  "entities": {
    "Book": {
      "rest": {
        "enabled": true,
        "path": "/BooksApi"
      }
    }
  }
}

--rest.methods

Stored procedures only. Replace allowed HTTP methods. Defaults to POST.

Example

dab update \
  RunReport \
  --rest true \
  --rest.methods GET,POST

Resulting config

{
  "entities": {
    "RunReport": {
      "rest": {
        "enabled": true,
        "methods": [ "get", "post" ]
      }
    }
  }
}

Note

Supplying --rest.methods while REST is disabled has no effect.

-s, --source

Update the underlying database object.

Example

dab update \
  Book \
  --source dbo.Books

Resulting config

{
  "entities": {
    "Book": {
      "source": {
        "object": "dbo.Books",
        "type": "table"
      }
    }
  }
}

--source.key-fields

For views or tables without an inferred PK. Replaces existing keys. Not valid for stored procedures.

Example

dab update \
  SalesSummary \
  --source.type view \
  --source.key-fields "year,region"

Resulting config

{
  "entities": {
    "SalesSummary": {
      "fields": [
        { "name": "year", "primary-key": true },
        { "name": "region", "primary-key": true }
      ]
    }
  }
}

Note

Using --source.key-fields with stored procedures is not allowed.

--source.params

Stored procedures only. Replace parameter defaults.

Note

In the v1.7 prerelease CLI, --source.params is deprecated. Use --parameters.name/--parameters.description/--parameters.required/--parameters.default.

Example

dab update \
  RunReport \
  --source.type stored-procedure \
  --source.params "year:2024,region:west"

Resulting config

{
  "entities": {
    "RunReport": {
      "source": {
        "parameters": [
          { "name": "year", "required": false, "default": "2024" },
          { "name": "region", "required": false, "default": "west" }
        ]
      }
    }
  }
}

Note

Using --source.params with tables or views is not allowed.

--source.type

Change the source object type.

Example

dab update \
  Book \
  --source.type view

Resulting config

{
  "entities": {
    "Book": {
      "source": {
        "type": "view",
        "object": "Book"
      }
    }
  }
}

--parameters.name

Stored procedures only. Comma-separated list of parameter names.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.required "true,true" \
  --parameters.description "Beginning of date range,End of date range"

Resulting config

{
  "entities": {
    "GetOrdersByDateRange": {
      "source": {
        "parameters": [
          {
            "name": "StartDate",
            "description": "Beginning of date range",
            "required": true
          },
          {
            "name": "EndDate",
            "description": "End of date range",
            "required": true
          }
        ]
      }
    }
  }
}

--parameters.description

Stored procedures only. Comma-separated list of parameter descriptions aligned to --parameters.name.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.description "Beginning of date range,End of date range"

--parameters.required

Stored procedures only. Comma-separated list of true/false values aligned to --parameters.name.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "StartDate,EndDate" \
  --parameters.required "true,true"

--parameters.default

Stored procedures only. Comma-separated list of default values aligned to --parameters.name.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  GetOrdersByDateRange \
  --parameters.name "CustomerID" \
  --parameters.default "null"

--fields.name

Name of the database column to describe.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  Products \
  --fields.name Id \
  --fields.primary-key true \
  --fields.description "Product Id"

Resulting config

{
  "entities": {
    "Products": {
      "fields": [
        {
          "name": "Id",
          "description": "Product Id",
          "primary-key": true
        }
      ]
    }
  }
}

--fields.alias

Alias for the field. Use a comma-separated list aligned to --fields.name.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  Products \
  --fields.name Id \
  --fields.alias product_id

--fields.description

Description for the field. Use a comma-separated list aligned to --fields.name.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  Products \
  --fields.name Id \
  --fields.description "Product Id"

--fields.primary-key

Primary key flag for the field. Use a comma-separated list of true/false values aligned to --fields.name.

Note

This option is available only in the v1.7 prerelease CLI (currently RC). Install with dotnet tool install microsoft.dataapibuilder --prerelease.

Example

dab update \
  Products \
  --fields.name Id \
  --fields.primary-key true

-c, --config

Path to the configuration file.

Example

dab update \
  Book \
  --description "Updated description" \
  --config dab-config.json

--help

Display the help screen.

Example

dab update --help

--version

Display version information.

Example

dab update --version

Important

Changing source type may invalidate other properties. For example, views always require key-fields; stored procedures cannot define key-fields.

  • Last updated on