Document the datasources.update_hyper_data method

[vogelsgesang]

Adds the documentation for the datasources.update_data method added in PR #891

[jacalata]

lgtm, @dzucker-tab might want to skim it

[bcantoni]

@vogelsgesang this looks good. Couple of minor things I would change for consistency with other methods:

For the docs link, suggest linking into the rest_api_ref.htm section directly:

Update Data in Hyper Data Source
https://help.tableau.com/current/api/rest_api/en-us/REST/rest_api_ref.htm#update_data_in_hyper_data_source

Because this is new, add a Version section before Parameters explaining where it's available:

Version
This endpoint is available with REST API version 3.12 and up.

With those changes I can time merging this when the next release happens.

[vogelsgesang]

This endpoint is available with REST API version 3.12 and up.

Afaict, this is only in version 3.13. At least that's what the code in TSC currently states...

With those changes I can time merging this when the next release happens.

Is there already a timeline for the next release?

[vogelsgesang]

two more comments from @dzucker-tab (accidentally posted directly on the commit, and not in the pull request):

too late to make this datasource.update_hyper_data() ?

We can still rename this as there was no release, yet. @jonas-eckhardt any preference re update_data vs. update_hyper_data?

datasource_or_connection_item | Either a DataSourceItem or a ConnectionItem. For a data source with a single connection, use a DataSourceItem. For datasources with multiple connections, use a ConnectionItem to specify the data to update.

I think we should not tell customers to use a DataSourceItem for data sources with a single connection. Such a wording might even incentivize customers to think: "Hm... I have a ConnectionItem which I want to update. Let's check how many connections the corresponding datasource has. Since if it has only one, I should use the DataSourceItem instead of the ConnectionItem."

Why do you think we should change this from its current formulation?

I think there might be a solution which addresses both your and my concerns, but I am not sure which formulation that is because I currently don't understand your concern with the docs currently in review

[bcantoni]

Is there already a timeline for the next release?

No but we're aiming for this week or next.

[dzucker-tab]

@vogelsgesang

RE:

We can still rename this as there was no release, yet. @jonas-eckhardt any preference re update_data vs. update_hyper_data?

Advocating for this for the same reason as the REST API reference labelling - to differentiate the type of data being updated as it could be referring to any of several things.

RE:

datasource_or_connection_item | Either a DataSourceItem or a ConnectionItem. For a data source with a single connection, use a DataSourceItem. For datasources with multiple connections, use a ConnectionItem to specify the data to update.

I take your point. Instead, how about:

datasource_or_connection_item | Either a DataSourceItem or a ConnectionItem. With a ConnectionItem, you can specify the data to update for data sources with one or more connections. With DataSourceItem, you can specify the data to update without providing a connection LUID, but only for data sources that have a single connection.

[vogelsgesang]

renamed the method from update_data to update_hyper_data in #906.

datasource_or_connection_item | Either a DataSourceItem or a ConnectionItem. With a ConnectionItem, you can specify the data to update for data sources with one or more connections. With DataSourceItem, you can specify the data to update without providing a connection LUID, but only for data sources that have a single connection.

Do our users know what a connection LUID is? and that the difference between ConnectionItem and DataSourceItem is the presence/absence of a connection LUID?

[jacalata]

datasource_or_connection_item | Either a DataSourceItem or a ConnectionItem. With a ConnectionItem, you can specify the data to update for data sources with one or more connections. With DataSourceItem, you can specify the data to update without providing a connection LUID, but only for data sources that have a single connection.

how about this?

datasource_or_connection_item | Either a DataSourceItem or a ConnectionItem. You can use a DatasourceItem if the data source has only a single connection. In all other cases, you must use a ConnectionItem.

[dzucker-tab]

@jacalata RE:

datasource_or_connection_item | Either a DataSourceItem or a ConnectionItem. You can use a DatasourceItem if the data source has only a single connection. In all other cases, you must use a ConnectionItem.

I started with something close to this, Adrian was concerned that it amounted to pushing folks to use DatasourceItem.

@vogelsgesang RE:

Do our users know what a connection LUID is? and that the difference between ConnectionItem and DataSourceItem is the presence/absence of a connection LUID?

IMO, if folks don't know what a LUID is, they should find out, but if that is a stopper, how about:

datasource_or_connection_item | Either a DataSourceItem or a ConnectionItem. With a ConnectionItem, you can specify the data to update for data sources with one or more connections. With DataSourceItem, you can specify the data to update without providing a connection ID, but only for data sources that have a single connection.