SAP HANA hdbtable and hdbview: Design-Time Objects and Troubleshooting

01What hdbtable and hdbview do

In SAP HANA development, .hdbtable and .hdbview files describe database objects as design-time artifacts. A deployment or activation process reads the definition and creates or updates the corresponding catalog object in the target schema.

An .hdbtable artifact defines a table, including its columns, data types, keys, and selected table properties. An .hdbview artifact defines a SQL view through a query over existing database objects. The two artifacts therefore have different ownership and lifecycle characteristics: a table stores data, while a view derives a result from other objects.

For broader context, see the SAP HANA development overview, which places these artifacts alongside other development approaches.

02How an hdbtable artifact is structured

An .hdbtable file expresses the table definition in design-time form. A basic definition normally includes the table type, columns, and primary key information where a key is required by the application model.

tableType = COLUMNSTORE;
columns = {
    ID       = { sqlType = INTEGER; };
    NAME     = { sqlType = NVARCHAR; length = 100; };
    CREATED  = { sqlType = DATE; };
};
primaryKey.pk = ["ID"];

Use column-store tables for analytical and general-purpose workloads that fit SAP HANA's columnar processing model. Choose data types and lengths deliberately because changing a design-time definition can trigger a table alteration, data movement, or an activation failure depending on the change.

A table artifact should also have a clear dependency boundary. Keep application-owned tables separate from generated or externally managed objects, and use stable names for keys and columns so dependent views do not break during routine deployments.

03How an hdbview artifact is structured

An .hdbview file represents a SQL view whose definition is evaluated against source tables or other compatible database objects. A typical artifact identifies the target schema and supplies a query.

schema = "APP_SCHEMA";
query = "select ID, NAME from APP_SCHEMA.CUSTOMER";

The query must reference objects that are available in the target deployment context. Dependencies can include tables, other views, synonyms, and objects delivered by a separate application component. The deployment order must make those dependencies available before the view is activated.

Keep the view projection intentional. Selecting only the columns needed by the consuming service reduces coupling and makes later table changes easier to manage.

04hdbview and calculation view differences

An .hdbview is a SQL view definition. Its logic is expressed as a SQL query, and its behavior follows SQL view semantics. A calculation view is a separate modeling artifact with graphical or SQL-based nodes, metadata, semantics, and analytical modeling options.

Use an .hdbview when a readable SQL projection, join, filter, or reusable relational abstraction is sufficient. Use a calculation view when the model needs calculation-view semantics, reusable nodes, measures, dimensions, input parameters, or a structured analytical model. The SAP HANA calculation views guide explains the separate calculation-view workflow.

The choice should follow the consumer and the model's required behavior rather than the file extension alone. A view used by a transactional service may benefit from a small SQL definition, while an analytical model may need the richer metadata and modeling features of a calculation view.

05Deployment and activation workflow

Treat an artifact deployment as a dependency graph rather than as an isolated file copy. A practical sequence is:

1. Create or update the table definition.
2. Deploy the table artifact to the intended schema.
3. Confirm that the table is active and contains the expected columns.
4. Deploy the view artifact.
5. Validate the view definition and test it with representative data.
6. Deploy dependent services or models after the database objects are active.

Design-time source files and catalog objects have different lifecycles. A file can be present in a project while its database object is missing, inactive, or still based on an older deployment. Always verify the target system and schema before concluding that a deployment completed successfully.

For projects that use SQLScript alongside database artifacts, the SAP HANA SQLScript procedures guide provides related implementation context.

06Troubleshooting activation failures

Activation failures usually come from a small set of operational causes: an invalid definition, a missing dependency, insufficient privileges, an unavailable schema, or an incompatible change to an existing object.

Start with the activation log and identify the first reported object failure. Later errors often result from that initial failure. Check the exact target schema, object names, quoted identifiers, data types, key definitions, and referenced columns before changing the artifact.

For an .hdbtable failure, inspect column definitions, key syntax, duplicate column names, unsupported properties, and changes that conflict with existing data. For an .hdbview failure, inspect the query independently, confirm that every source object exists, and verify that referenced columns and aliases are unambiguous.

When the project uses a containerized deployment model, review the dependency declarations and grants that make external objects available. The SAP HANA HDI containers guide covers the related container-based deployment concepts.

07Managing changes safely

Plan table changes according to their effect on existing data. Adding a nullable column is generally easier to roll out than changing a populated column's type, reducing its length, or replacing a key. Test destructive or data-rewriting changes against a copy of representative data before applying them to a shared system.

For views, preserve the contract expected by consuming applications. Renaming a projected column, changing its data type, or altering null behavior can break services even when the view still activates successfully.

Use version control for both artifacts and deployment configuration. Record the intended schema, dependency order, and compatibility impact in the same change so another operator can reproduce the deployment and diagnose a failure.

08Operational checklist

Before deploying an .hdbtable or .hdbview change, verify the following:

• The artifact belongs to the intended application component.
• The target schema and deployment destination are correct.
• Referenced tables, views, synonyms, and grants are available.
• Table keys and column definitions match the consuming code.
• View projections preserve the expected interface.
• Existing data has been considered for table alterations.
• The activation log has been reviewed after deployment.
• A representative query or service test has succeeded.

This checklist separates source-control validation from database validation. Both are needed because a syntactically valid artifact can still fail when its target dependencies or privileges are incomplete.