Workspace Object Identification

An instance of a workspace object can be uniquely identified using an object identifier (object ID) combined with its object type. This means two objects of different object types can have the same object ID.

Object ID is a string limited to 255 characters and consisting of characters a-Z0-9._-.

Referencing an Object

All relationships are built directly into the object structure in the logical and physical layers. For analytics objects, free-form content is allowed, except for metrics.

The following structure must be used to create a relationship between an analytics object and other objects.

{ 
  "identifier" :
  {
    "id" : STRING,
    "type" : "metric"|"analyticalDashboard"|...,
   }
}

For MAQL, a serialized form is used: {<type>/<id>}. For example:

SELECT SUM({fact/size}) WHERE {label/name} IN ("Special","Small")

In this structure, size is the object ID, and fact is the object type.

Object Origin

All objects in a workspace have a metadata property called origin:

{
  "data": {
    …,
    "meta": {
      "origin": {
         "originType": "NATIVE"|"PARENT",
         "originId": "STRING"
      }
    }
  }
}

The origin metadata shows whether an object is inherited from a parent workspace or native to the current workspace:

  • originId is the ID of the workspace from which the object comes.
  • NATIVE means the object is native to the current workspace (i.e., originId = current workspace ID).
  • PARENT means the object is inherited from a parent workspace (i.e., originId = parent workspace ID).

This allows you to quickly check if an object is native to the workspace or inherited from a parent, helping to determine if restrictions for inherited objects apply.

Accessing an Object via the API

You can access an object of object type <type> and object id <id> located in workspace <workspace-id> using the following GET API endpoint:

$HOST_URL/api/v1/entities/workspaces/<workspace-id>/<type>/<obj-id>

Custom Object ID Prefix

You can set a unique prefix for each workspace. When you create a new analytical object (like a metric, visualization, or dashboard) in that workspace, the prefix will automatically be added to its object ID. This makes seeing an object’s origin easy, especially in a complex workspace hierarchy. Prefixes also help avoid conflicts with identical object IDs in different workspaces.

For example, if you set a custom prefix like doc_demo_, you’ll see it when creating a new metric in the web interface:

Example of a custom prefix in metric ID

Note that:

  • Adding or changing the prefix won’t affect the IDs of existing objects.
  • The prefix is only applied when creating objects through the web interface or when the object ID is not explicitly defined.

If you create an object with a custom ID, you must manually add the prefix if you want it included.

Recommended Practices

When setting a custom prefix, we recommend the following:

  • End the prefix with a clear delimiter, like _, -, or .. This helps separate the prefix from the object’s raw ID.
  • Use parent workspace prefixes as a base for child prefixes, like EU_, EU-FR_, EU-FR-PARIS_, to create a clear hierarchy.
  • Make sure prefixes are unique and easy to tell apart. Avoid using similar prefixes, like EU_ and EU__.

Set a Custom Object ID Prefix for a Workspace

Using the API, you can set a custom object ID prefix for a workspace. This is done by accessing the workspace object through the following API endpoints:

  • /api/v1/entities/workspaces/<workspace_id>
  • /api/v1/layout/workspaces/<workspace_id>

Steps:

  1. To set a custom prefix, make this API call to the /api/v1/entities/workspaces/<workspace_id> endpoint:

    curl -X PATCH $HOST_URL/api/v1/entities/workspaces/<workspace_id> \
-H "Content-Type: application/vnd.gooddata.api+json" \
-H "Accept: application/vnd.gooddata.api+json" \
-H "Authorization: Bearer $API_TOKEN" \
-d '{
    "data": {
        "attributes": {
            "prefix": "<custom_object_prefix>"
        },
        "id": "<workspace_id>",
        "type": "workspace"
    }
}'

    This sets the custom object prefix <custom_object_prefix> for the workspace <workspace_id>.

  2. To verify that the prefix was successfully set, make a GET request to the same API endpoint:

    curl -X GET $HOST_URL/api/v1/entities/workspaces/<workspace_id> \
-H "Content-Type: application/vnd.gooddata.api+json" \
-H "Accept: application/vnd.gooddata.api+json" \
-H "Authorization: Bearer $API_TOKEN"

    You should see the <custom_object_prefix> in the prefix field, as shown below:

    {
    "data": {
        "id": "af3d7591d8e5420fbde7a6b210347cfa",
        "type": "workspace",
        "attributes": {
            "name": "documentationDemoWorkspace",
            "prefix": "doc_demo_"
        }
    },
    "links": {
        ...
    }
}

Object Identifiers in Older Versions of GoodData

Before the release on March 9, 2023, or before upgrading to GoodData.CN 2.3, object identifiers in workspace hierarchies worked differently.

For more details, see Changes to Workspace Object Identification.

This is important to consider if you are updating from an older version of GoodData.

Discontinued Object ID Prefix

Previously, objects inherited from a parent workspace had their object ID prefixed with the parent workspace ID. For example, if a metric with ID revenue was inherited from the workspace parent_workspace_id, its ID in the child workspace would be parent_workspace_id:revenue.

This system has been replaced by the object origin property.

Conflicting Object IDs

With the removal of object ID prefixes, you might encounter situations where two objects have the same ID. For instance, you might have a metric revenue in a child workspace and an inherited metric parent_workspace_id:revenue. Since prefixes are no longer used, both will now share the ID revenue.

In such cases, the “parent wins” strategy is applied, meaning that when you request the ID revenue, only the object from the highest workspace in the hierarchy will be returned, and the child object will be deleted.

List and Resolve Conflicting Object IDs

To identify objects with conflicting IDs, you can use these API endpoints:

  • /api/v1/action/workspaces/<workspaceId>/overriddenChildEntities:
    Lists objects in child workspaces overridden by objects in the workspace <workspaceId>.

  • /api/v1/actions/workspaces/<workspaceId>/inheritedEntityConflicts:
    Lists objects in parent workspaces that override objects in the workspace <workspaceId>.

To resolve these conflicts, you must either rename the objects to ensure unique IDs or delete the overridden objects.

You must make these changes using the declarative API, as the overridden objects are unavailable through the entity API. Depending on your hierarchy, use the following API endpoints:

  • For the whole organization: /api/v1/layout/organization
  • For all workspaces: /api/v1/layout/workspaces
  • For a single workspace: /api/v1/layout/workspaces/{workspaceId}/... (either analyticsModel or logicalModel)
Entity API Interface
Objects Organization