Migrate from the Data QnA API to the Conversational Analytics API

This guide describes key differences and steps for migrating your applications from the Data QnA API (dataqna.googleapis.com) to the Conversational Analytics API (geminidataanalytics.googleapis.com).

Provide feedback

If you encounter any discrepancies during the migration process, contact conversational-analytics-api-feedback@google.com.

Overview of key changes

The Conversational Analytics API introduces changes to the API endpoint, the service that the API uses, and the structure of API requests. The following table summarizes the key differences between the Data QnA API and the Conversational Analytics API and lists the required steps for migration.

Data QnA API Conversational Analytics API Required change
dataqna.googleapis.com endpoint geminidataanalytics.googleapis.com endpoint Update the API endpoint in your requests.
DataQuestionService service DataChatService service Update the service name in your requests.
project field in the AskQuestionRequest message parent field in the ChatRequest message Replace the project field with the parent field in your requests. For more information, see Replace project with parent for request routing.
datasource_ids field studio_references field Replace the datasource_ids field with the studio_references field in your requests. For more information, see Update references to Looker Studio data source IDs.
AgentConfig object ConversationOptions object Replace the AgentConfig object with the ConversationOptions object in your requests. For more information, see Enable Python analysis with ConversationOptions.
context field in the AskQuestionRequest message inline_context field in the ChatRequest message Replace the context field with the inline_context field in your requests. For more information, see Replace context with inline_context.

For examples of how to update your API request structures, see Examples: Update your API request structures.

Replace project with parent for request routing

In the Data QnA API, you use the project field within the AskQuestionRequest message to specify the Google Cloud project. In the Conversational Analytics API, the project field is deprecated within the ChatRequest message. Instead, you use the parent field to specify both the project and the location.

The following example shows the format for specifying the parent field:

parent: "projects/your_project_name/locations/global"

In the previous example, replace your_project_name with the name of your Google Cloud project.

Update references to Looker Studio data source IDs

In the Data QnA API, you use the datasource_ids field to provide a list of Looker Studio data source IDs. In the Conversational Analytics API, you use the studio_references field to provide a list of StudioDatasourceReference objects, each containing a single data source ID. For more information, see StudioDatasourceReferences.

Enable Python analysis with ConversationOptions

The AgentConfig object, which is used in the Data QnA API to enable tools, is not used by the DataChatService service in the Conversational Analytics API. To enable features such as Python analysis in the Conversational Analytics API, use the ConversationOptions object when you create or configure a data agent. For more information, see ConversationOptions.

Replace context with inline_context

In the Data QnA API, the AskQuestionRequest message includes a context field for inline contextual information. In the Conversational Analytics API, the context field is renamed to inline_context in the ChatRequest message. This change helps to distinguish inline context from other types of context that can be provided through data agents.

Examples: Update your API request structures

The following examples show how to adapt your requests to the new API structure when you migrate from the Data QnA API to the Conversational Analytics API. These examples cover BigQuery, Looker, and Looker Studio data sources.

BigQuery data source

This section provides an example of how to update your API requests for BigQuery data sources. The example shows how to update a request that asks for a bar graph that shows the top five states by the total number of airports.

The following code sample shows the request structure for the Data QnA API:

project: "projects/your_project_name"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 states by the total number of airports."
  }
}
context {
  datasource_references {
    bq {
      table_references {
        project_id: "your_project_id"
        dataset_id: "your_dataset_id"
        table_id: "your_table_id"
      }
    }
  }
}

The following code sample shows the updated request structure for the Conversational Analytics API:

messages {
  user_message {
    text: "Create a bar graph showing the top 5 states by the total number of airports."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    bq {
      table_references {
        project_id: "your_project_id"
        dataset_id: "your_dataset_id"
        table_id: "your_table_id"
      }
    }
  }

For the previous examples, you can replace the sample values as follows:

  • your_project_name: The name of your Google Cloud project.
  • your_project_id: The ID of your BigQuery project. To connect to a public dataset, specify bigquery-public-data.
  • your_dataset_id: The ID of the BigQuery dataset. For example, faa.
  • your_table_id: The ID of the BigQuery table. For example, us_airports.

Looker data source

This section provides an example of how to update your API requests for Looker data sources. The example shows how to update a request that asks for the count of orders by order status.

The following code sample shows the request structure for the Data QnA API:

project: "projects/your_project_name"
messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
context {
  datasource_references {
    looker {
      explore_references {
        looker_instance_uri: "https://your_company.looker.com"
        lookml_model: "your_model"
        explore: "your_explore"
      }
      credentials {
        oauth {
          secret {
            client_id: "your_looker_client_id"
            client_secret: "your_looker_client_secret"
          }
        }
      }
    }
  }
}

The following code sample shows the updated request structure for the Conversational Analytics API:

messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    looker {
      explore_references {
        lookml_model: "your_model"
        explore: "your_explore"
        looker_instance_uri: "https://your_company.looker.com"
      }
      credentials {
        oauth {
          secret {
            client_id: "your_looker_client_id"
            client_secret: "your_looker_client_secret"
          }
        }
      }
    }
  }
}

For the previous examples, you can replace the sample values as follows:

  • your_project_name: The name of your Google Cloud project
  • https://your_company.looker.com: The URI of your Looker instance
  • your_model: The name of your LookML model
  • your_explore: The name of your LookML Explore
  • your_looker_client_id: Your Looker client ID
  • your_looker_client_secret: Your Looker client secret

Looker Studio data source

This section provides an example of how to update your API requests for Looker Studio data sources. The example shows how to update a request that asks for a bar graph that shows the top five carriers.

The following code sample shows the request structure for the Data QnA API:

project: "projects/your_project_name"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
context {
  datasource_references {
    studio {
      datasource_ids: "your_data_source_id"
    }
  }
}

The following code sample shows the updated request structure for the Conversational Analytics API:

messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
parent: "projects/your_project_name/locations/global"
inline_context {
  datasource_references {
    studio {
      datasource_ids: "your_data_source_id"
    }
  }
}

For the previous examples, you can replace the sample values as follows:

  • your_project_name: The name of your Google Cloud project
  • your_data_source_id: The ID of your Looker Studio data source