Explore a database using the Flow Service API

This tutorial uses the Flow Service API to explore the contents and file structure of a third-party database.

Getting started

This guide requires a working understanding of the following components of Adobe Experience Platform:

The following sections provide additional information that you will need to know in order to successfully connect to a third-party database using the Flow Service API.

Gather required credentials

This tutorial requires you to have a valid connection with the third-party database you wish to ingest data from. A valid connection involves your database’s connection specification ID and connection ID. More information about creating a database connection and retrieving these values can be found in the source connectors overview.

Reading sample API calls

This tutorial provides example API calls to demonstrate how to format your requests. These include paths, required headers, and properly formatted request payloads. Sample JSON returned in API responses is also provided. For information on the conventions used in documentation for sample API calls, see the section on how to read example API calls in the Experience Platform troubleshooting guide.

Gather values for required headers

In order to make calls to Platform APIs, you must first complete the authentication tutorial. Completing the authentication tutorial provides the values for each of the required headers in all Experience Platform API calls, as shown below:

All resources in Experience Platform, including those belonging to Flow Service, are isolated to specific virtual sandboxes. All requests to Platform APIs require a header that specifies the name of the sandbox the operation will take place in:

All requests that contain a payload (POST, PUT, PATCH) require an additional media type header:

Explore your data tables

Using the connection ID for your database, you can explore your data tables by performing GET requests. Use the following call to find the path of the table you wish to inspect or ingest into Platform.

API format

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=root

Request

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/connections/6990abad-977d-41b9-a85d-17ea8cf1c0e4/explore?objectType=root' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns an array of tables from your database. Find the table you wish to bring into Platform and take note of its path property, as you are required to provide it in the next step to inspect its structure.

[
    {
        "type": "table",
        "name": "test1.Mytable",
        "path": "test1.Mytable",
        "canPreview": true,
        "canFetchSchema": true
    },
    {
        "type": "table",
        "name": "test1.austin_demo",
        "path": "test1.austin_demo",
        "canPreview": true,
        "canFetchSchema": true
    }
]

Inspect the structure of a table

To inspect the structure of a table from your database, perform a GET request while specifying the path of a table as a query parameter.

API format

GET /connections/{BASE_CONNECTION_ID}/explore?objectType=table&object={TABLE_PATH}

Request

curl -X GET \
    'https://platform.adobe.io/data/foundation/flowservice/connections/6990abad-977d-41b9-a85d-17ea8cf1c0e4/explore?objectType=table&object=test1.Mytable' \
    -H 'Authorization: Bearer {ACCESS_TOKEN}' \
    -H 'x-api-key: {API_KEY}' \
    -H 'x-gw-ims-org-id: {ORG_ID}' \
    -H 'x-sandbox-name: {SANDBOX_NAME}'

Response

A successful response returns the structure of the specified table. Details regarding each of the table’s columns are located within elements of the columns array.

{
    "format": "flat",
    "schema": {
        "columns": [
            {
                "name": "TestID",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            },
            {
                "name": "Name",
                "type": "string",
                "xdm": {
                    "type": "string"
                }
            }
        ]
    }
}

Next steps

By following this tutorial, you have explored your database, found the path of the table you wish to ingest into Platform, and obtained information regarding its structure. You can use this information in the next tutorial to collect data from your database and bring it into Platform.