Spanner docs are outdated

Spanner docs still talk about checking out a session and then doing operations on that such as session.snapshot and session.batch.
We changed the API long time back where such operations can be done directly on the database object and that is the API we want to promote. Please audit all the docs to scrub out all the calls directly made on session object and replace those with calls on Database object. This should be doe before Beta since we expect an uptick in usage once we mark the client as Beta and we want to people to use the preferred API.

@lukesneeringer

cc @lukesneeringer @bjwatson @danoscarmike

Also the snapshot doc should talk about nuances of using Snapshots with multi use and single use and the fact that users need to call begin if they need to have multiple pending operations.

I presume we will drop discussion of sessions from the narrative / usage docs, but leave the API docs pages in place (since users might still come across them, e.g. in tracebacks).

Yeah I agree leaving the API docs pages in place is OK. We can probably emphasise on those API docs that most users need not interact with these objects directly.

@lukesneeringer

cc @lukesneeringer @danoscarmike
I don;t think this has been completely resolved. For eg the transactions doc still talks about using a session and does not mention database.run_in_transaction method:
https://googlecloudplatform.github.io/google-cloud-python/stable/spanner/transaction-usage.html

Ditto for snapshots page:
https://googlecloudplatform.github.io/google-cloud-python/stable/spanner/snapshot-usage.html

Can we please reopen this bug? I would also like this to be fixed before marking the client library as GA.

I'm trying to write tests for spanner and I'm also having problems trying to use it from reading the documentation.

@chemelnucfin

@chemelnucfin Can you reopen this? I do not have permissions.

@vkedia

@vkedia so just to make sure, all these methods currently on the session object should be directly done on the database object? Is the session object still needed then?
Any other methods which should be directly on the database?

def snapshot(self, **kw):
def read(self, table, columns, keyset, index='', limit=0):
def execute_sql(self, sql, params=None, param_types=None, query_mode=None):
def batch(self):
def transaction(self):
def run_in_transaction(self, func, *args, **kw):

Users should never have to use session object for anything. If possible we should make it non public.
Also we removed the read and execute_sql methods from database. So users need to create a snapshot to do that.

@chemelnucfin

@chemelnucfin Is there a PR corresponding to this issue? (Other than the last couple of tests, I think it is the last GA blocking item.)

Closed via #4610, #4611, #4409, #4630

docs: add samples from bigtable (#38)

Navigation Menu

Repository navigation

Spanner docs are outdated #3740

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Spanner docs are outdated #3740

Description

Activity

vkedia commented on Aug 7, 2017

vkedia commented on Aug 7, 2017

tseaver commented on Aug 9, 2017

vkedia commented on Aug 9, 2017

vkedia commented on Nov 17, 2017

chemelnucfin commented on Nov 17, 2017

vkedia commented on Nov 17, 2017

chemelnucfin commented on Dec 1, 2017

vkedia commented on Dec 1, 2017

lukesneeringer commented on Dec 18, 2017

chemelnucfin commented on Dec 20, 2017

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions