Acquiring Object Identifiers for Project Metadata

Related Tags: data modeling project administration

This article provides information on how to acquire identifiers for your projects and your project metadata. GoodData provides a number of methods for acquiring identifiers and, in some cases, special methods need to be applied to acquire the identifiers.

Contents:

Identifier Types

The term “identifier” covers a range of types of references to objects in your project. Below is a brief explanation of each type.

Display Name

The display name for an object is the value that is shown to users. If you see a column for Opportunity (Closed) in your report, the display value for this date is what is displayed in the report column. This setting is also referred to as the Title of an object.

This value is available through all of the interfaces. See Object Identifier Interfaces.

Identifier for projects

Internally, projects are identified by a long hash value that is unique throughout the platform. This value can be parsed from the URL whenever the project is loaded. In short form, this value is sometimes referred to as the PID.

Project identifiers are needed for making changes to your projects via API. All API calls that modify individual projects must include the project ID as part of the submitted URL.

Project identifiers can be extracted from the GoodData Portal or through the GoodData APIs. For more information, see Project Identifiers.

Identifier for project objects

You can make explicit references to objects in the project. The following example references the Author attribute that is part of the Twitter dataset:
attr.twitter.author

These references are typically used when building MAQL statements and must be unique within the project. They do not need to be unique throughout the platform. When adding these references in MAQL statements, they must be bracketed in curly braces:
{attr.twitter.author}

These identifiers apply to any object that is part of a project: logical data model, metrics, reports, or dashboards.

NOTE: Some objects are automatically created in the logical data model by the platform; the identifiers for these must be retrieved from the gray pages and may not be available through other interfaces.

For more information, see Acquiring Special Identifiers for Data Model Objects.

Identifier for reporting objects

Identifiers for reporting objects, including objects in the logical data model, can be retrieved from the GoodData Portal. When an object is selected in the GoodData Portal, the end of the URL should contain a reference similar to the following:
obj/380

The value 380 identifies the object within the project. These values are applicable to the following reporting objects:

  • dashboards
  • dashboard tabs - these identifiers include a hash value at the end of the reference to the dashboard object, as in the following:
    /obj/2687|8155447e7382
    
  • reports (when selected in the Reports page)
  • datasets (in the Manage page)
  • metrics (in the Manage page)
  • attributes (in the Manage page)
  • facts (in the Manage page)

Object URI

Each reporting object in the platform can be referenced by a URI, which includes the project identifier where the object is stored and the numeric identifier for the project. For example:

/gdc/md/zy7yqdbijoxfutkxnb801l6nu6xntv0e/obj/380

The above object references object 380 in the project whose identifier is zy7yqdbijoxfutkxnb801l6nu6xntv0e.

A typical use of these identifiers is when exporting and importing these individual objects through API.

Attribute elements

Attributes have individual elements contained within them, which hold the individual values associated with the attribute. These identifiers can be referenced by their SLI hash values, as in the following example:

/gdc/md/zy7yqdbijoxfutkxnb801l6nu6xntv0e/obj/380/elements?id=321122

In the above, the identifier for the attribute element is 321122. Using the URI above, you can access the object definition for this specific attribute element.

Object Identifier Interfaces

GoodData provides multiple interfaces through which you can acquire identifiers. The recommended interface to use depends on whether you are acquiring identifiers for individual objects or whether you are needing them for script or API access.

InterfaceDescription
GoodData PortalThrough your individual project, you can acquire the project identifier and object numbers.
Gray PagesThrough the gray pages, you can access the identifiers of individual objects in your project, including URIs.
GoodData Extension ToolThis plugin for the Chrome browser enables you to jump directly to the gray page for objects that you select in your project, among other functions. For accessing specific, individual objects, this tool is the fastest method for acquiring data on resources.
CloudConnect DesignerThrough the LDM Modeler in CloudConnect Designer, you can acquire most of the identifiers for objects in your project’s logical data model. For more information, seeAcquiring data model object identifiers.
GoodData APIsThrough the GoodData APIs, you can query for individual object identifiers, which may be used to make queries for lists of objects organized within that object.

Acquiring Project Identifiers

Acquiring project identifier from the GoodData Portal

The easiest way to acquire an individual project identifier is to open the project in the GoodData Portal. If you’re logged into a project, you can acquire the internal project identifier from the URL for the report. Suppose you have opened a project in the GoodData Portal:

https://secure.gooddata.com/#s=/gdc/projects/a8w32109wddkxjmsqysgut4nmq8bss44|projectDashboardPage|/gdc/md/a8w32109wddkxjmsqysgut4nmq8bss44/obj/2687

The project identifier is the following:

a8w32109wddkxjmsqysgut4nmq8bss44

This value appears twice in the preceding URL, which references the project and an individual object within the project. Since the individual object is unique only within the project, it must contain a reference to the project ID in order to maintain uniqueness across all objects in the platform.

Acquiring project identifiers via API

Via API call, you may also acquire project identifiers for the projects to which you have access. When the following call is issued after you have logged in, the returned values include the project identifiers for all projects in your organization to which you have access:

https://secure.gooddata.com/gdc/account/profile/{profile-id}/projects

where: {profile-id} is the identifier for your user profile. This profile ID is returned when you successfully log into the platform via API.

For more information, see API Documentation.

Acquiring data model object identifiers

When building MAQL DML statements, you may require the internal identifiers of data model objects. For example, if you are building MAQL DDL statements to modify your logical data model or MAQL DML statements to modify your project data, you must reference these identifiers, which are available through one of the following methods:

  1. CloudConnect Designer: In the logical data model, you can select a dataset or field in a dataset, and the identifier is displayed in the Details sidebar:
    Acquiring object identifiers from CloudConnect
    Identifier in CloudConnect
  2. Extension Tool: If you have installed the Extension Tool for Chrome, you can navigate to the Manage page in the GoodData Portal to select the attribute, fact, or dataset whose identifier you wish to retrieve. Then, from the Extension toolbar, select Obj. The object’s gray page is displayed:
    Acquiring identifiers from GoodData Extension Tool
    Identifier through the GoodData Extension Tool

    For more information on installing and using the Extension Tool, see GoodData Extension Tool for Chrome.
  3. GoodData APIs: You may use the GoodData APIs to retrieve object identifiers based on their type. For example, a GET to the following API returns a list of all attributes in your project (<project-id>:
    /gdc/md/<project-id>/query/attributes
  4. Gray Pages: You can navigate the gray pages hierarchy for your project to locate this information. However, the Extension Tool is easier to use. For more information on accessing the gray pages, see Accessing Gray Pages for a Project.

Acquiring Special Identifiers for Data Model Objects

Some data model object identifiers are not available through the logical data model in CloudConnect Designer or in the GoodData Portal. The sections below outline the steps required to retrieve identifiers that are not visible through these interfaces.

Acquiring identifiers to delete records of a dataset

A common task is to remove records from a dataset based on an attribute-derived condition. In English, such a deletion might be, “Delete all facts from the dataset where the Author attribute value is ‘GoodData’.”

To do so, you need to acquire three different identifiers from the data model:

  1. The identifier for the attribute
  2. The identifier for the label of the attribute

    NOTE: When deleting a specific set of facts from a fact table, you must build your testing condition by referencing an attribute label. This structure is specific to MAQL DML.

  3. The identifier for the rows in the dataset you wish to remove

    NOTE: Through MAQL DML, you cannot reference the fact table directly.

Acquiring object identifiers for attribute labels

When you are deleting records from a set of facts based on a specific contextual condition, the test condition (WHERE clause) must reference a label of an attribute.

NOTE:You cannot reference the parent attribute in the DELETE to remove the fact records.

Depending on how the attribute label was created, you can retrieve its internal identifier from one of the following ways:

  • When an attribute is created, a hidden attribute label is automatically created. If there are no other labels for the attribute, you must use this one. You may retrieve the label’s identifier through the gray pages or the GoodData Extension Tool. For more information, see Acquiring identifiers for hidden attribute labels.
  • If the attribute label was explicitly created in the logical data model for the project, you may retrieve it from CloudConnect or through the above method in the gray pages. For more information, see Acquiring identifiers for explicitly created attribute labels.

Acquiring identifiers for explicitly created attribute labels

For attribute labels that have been explicitly created in the logical data model, you can retrieve the identifiers from the logical data model in CloudConnect. This method only works if you have created explicit attribute labels that you wish to use.

Steps:

  1. Open the project in CloudConnect. Open the logical data model in the project.
  2. Select the dataset containing the attribute label. Click Edit.
  3. In the Attributes and Facts window, click the Show identifiers checkbox. The attribute label’s identifier is displayed in a new column:
    Attribute label identifier in CloudConnect
    Attribute label identifier in CloudConnect

Acquiring identifiers for hidden attribute labels

When an attribute is created, a hidden attribute label is automatically created within the dataset. This attribute is not available for use through common interfaces such as CloudConnect or the GoodData Portal.

To acquire the necessary identifiers to build the MAQL DML statements, please complete the following steps.

NOTE: This method of acquiring identifiers is best managed by using the GoodData Extension Tool, a toolbar that can be integrated into your Chrome browser. For more information on downloading and installing the GoodData Extension Tool, see GoodData Extension Tool for Chrome.

Steps:

  1. In the GoodData Portal menu, select Manage > Attributes. Select the attribute whose label you wish to retrieve.
  2. Locate the display name of the attribute of interest.
  3. Locate the resource page:
    1. If you are using the GoodData Extension Tool, click the drop-down and select Obj.
    2. If you are not using the GoodData Extension Tool:
  4. To access the object directly from the gray pages, retrieve the URL from the address bar. Suppose the URL is the following:
    https://secure.gooddata.com/#s=/gdc/projects/njy3r40rc9s4jvrm0y9cqyfghxlo1osu|objectPage|/gdc/md/njy3r40rc9s4jvrm0y9cqyfghxlo1osu/obj/380
    
  5. In the displayed page, retrieve the project identifier (njy3r40rc9s4jvrm0y9cqyfghxlo1osu in the above example) and object index number (380).
  6. You can access the attribute object in the gray pages by building an URL from these data elements in the following format:
    https://secure.gooddata.com/gdc/md/njy3r40rc9s4jvrm0y9cqyfghxlo1osu/obj/380
    
  7. The resource for the attribute is displayed:
    Attribute resource in the gray pages
    Attribute resource in the gray pages
  8. In the first step, locate the displayForm section. Within this section, locate the identifier value. This value is the identifier for the hidden attribute label. It should be in the form of label.*.
  9. In the attribute listing section, locate the meta section. Then, locate the value for identifier here. This value is the identifier for the attribute. It should be in the form of attr.*.
  10. Both of these retrieved values are required for deleting facts from a dataset.

Tip:Down further on the page is a second meta section. Here, you can locate the identifiers for explicitly defined attribute labels.

Tip:If you navigate into the elements area from the gray page, you can review the data values in the attribute label to verify that the values you want to remove are present. This area also becomes an effective way to verify that the deletion has occurred.

Acquiring object identifiers for attributes of facts

In this example, you must acquire the identifier for the attribute related to the set of facts. This identifier provides the means of identifying the attributes in the fact table that contain references to other attributes and dimensions.

Steps:

  1. In the GoodData Portal, select Manage > Attributes.
  2. Locate the “Records Of” attribute.
  3. To locate its identifier, you may use the Obj menu item in the Extension Tool, or you may build the URL from the “Records Of” attribute to access the gray page directly. For more information on these techniques, see Acquiring identifiers for hidden attribute labels.
  4. Typically, the identifier is of the following form, although this is not always the case: attr.(DatasetName).factsof
  5. You may use this reference as a lookup into the fact table based on an attribute referenced in a WHERE clause.

Acquiring object identifiers for date objects

GoodData provides a proprietary date object that can be used for managing dates in your project.

  • When this object is selected in CloudConnect Designer, its identifier is displayed in the Details sidebar.

When the date dimension is created in the logical data model, a set of attribute labels are automatically created in the data model, one for each supported date format. These attribute labels must be referenced for operations such as deleting fact data based on dates.

NOTE: Storing date data in a Date Fact entity in your dataset is considered a legacy method and is not recommended.

Please complete the following steps to acquire the attribute label identifiers for date dimensions from the gray pages or the GoodData Portal.

Steps:

  1. In the GoodData Portal, select Manage > Datasets.
  2. Select the dataset for the date dimension.
  3. In the Data Set page, click the name of the basic attribute. It should be in the form of Date (NameOfLDMObject).
  4. In the Attribute page, you can see all of the labels associated with this date attribute.
  5. Examples of attribute label identifiers for each of the supported date formats are listed below.
  6. You may also acquire the explicit identifiers from the gray page for this attribute.
    1. Use the Obj menu item in the GoodData Extension Tool or navigate to the appropriate page in the gray pages. For more information, see Acquiring identifiers for hidden attribute labels.
    2. In the gray page for the date attribute, locate the displayForms section.
    3. In each meta section, locate the title, which identifies the format for that display form. Then, locate the value for the identifier, which must be used in any references in your MAQL statements.

Suppose you have a Date dimension called tweet. Below, you can review the labels for the Date attribute, which are automatically generated in the logical data model in the project:

LabelLabel Identifier
mm/dd/yyyy (tweet)tweet.date.mmddyyyy
yyyy-mm-dd (tweet)tweet.date.yyymmdd
m/d/yy (no leading zeroes) (tweet)tweet.date.mdyy
Long (Mon, Jan 1, 2010) (tweet)tweet.date.long
dd/mm/yyyy (tweet)tweet.date.ddmmyyyy
dd-mm-yyyy (tweet)tweet.date.eddmmyyyy