{"action":"created","comment":{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/comments/35349255","id":35349255,"diff_hunk":"@@ -236,3 +236,189 @@ Delete a table:\n    >>> dataset = client.dataset('dataset_name')\n    >>> table = dataset.table(name='person_ages')\n    >>> table.delete()  # API request\n+\n+Jobs\n+----\n+\n+Jobs describe actions peformed on data in BigQuery tables:\n+\n+- Load data into a table\n+- Run a query against data in one or more tables\n+- Extrat data from a table\n+- Copy a table\n+\n+List jobs for a project:\n+\n+.. doctest::\n+\n+   >>> from gcloud import bigquery\n+   >>> client = bigquery.Client()\n+   >>> jobs = client.jobs()  # API request\n+   >>> [(job.job_id, job.type, job.created, job.state) for job in jobs]\n+   ['e3344fba-09df-4ae0-8337-fddee34b3840', 'insert', (datetime.datetime(2015, 7, 23, 9, 30, 20, 268260, tzinfo=<UTC>), 'done')]\n+\n+Querying data (synchronous)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Run a query which can be expected to complete within bounded time:\n+\n+.. doctest::\n+\n+   >>> from gcloud import bigquery\n+   >>> client = bigquery.Client()\n+   >>> query = \"\"\"\\\n+   SELECT count(*) AS age_count FROM dataset_name.person_ages\n+   \"\"\"\n+   >>> results = client.query(query, timeout_ms=1000)\n+   >>> while not results.job_complete:\n+   ...    time.sleep(10)\n+   ...    results.reload()  # API request\n+   >>> results.schema\n+   [{'name': 'age_count', 'type': 'integer', 'mode': 'nullable'}]\n+   >>> results.rows\n+   [(15,)]\n+\n+.. note::\n+   \n+   If the query takse longer than the timeout allowd, ``results.job_complete``\n+   will be False:  we therefore poll until it is completed.\n+\n+Querying data (asynchronous)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Background a query, loading the results into a table:\n+\n+.. doctest::\n+\n+   >>> from gcloud import bigquery\n+   >>> client = bigquery.Client()\n+   >>> query = \"\"\"\\\n+   SELECT firstname + ' ' + last_name AS full_name,\n+          FLOOR(DATEDIFF(CURRENT_DATE(), birth_date) / 365) AS age\n+    FROM dataset_name.persons\n+   \"\"\"\n+   >>> dataset = client.dataset('dataset_name')\n+   >>> table = dataset.table(name='person_ages')\n+   >>> job = client.query_async(query,\n+   ...                          destination=table,\n+   ...                          write_disposition='truncate')\n+   >>> job.job_id\n+   'e3344fba-09df-4ae0-8337-fddee34b3840'\n+   >>> job.type\n+   'load'\n+   >>> job.created\n+   None\n+   >>> job.state\n+   None\n+\n+.. note::\n+\n+   - ``gcloud.bigquery`` generates a UUID for each job.\n+   - The ``created`` and ``state`` fields are not set until the job\n+     is submitted to the BigQuery back-end.\n+\n+Then, begin executing the job on the server:\n+\n+.. doctest::\n+\n+   >>> job.submit()  # API call\n+   >>> job.created\n+   datetime.datetime(2015, 7, 23, 9, 30, 20, 268260, tzinfo=<UTC>)\n+   >>> job.state\n+   'running'\n+\n+Poll until the job is complete:\n+\n+.. doctest::\n+\n+   >>> import time\n+   >>> while job.state == 'running':\n+   ...     time.sleep(10)\n+   ...     job.reload()  # API call\n+   >>> job.state\n+   'done'\n+   >>> job.ended\n+   datetime.datetime(2015, 7, 23, 9, 30, 21, 334792, tzinfo=<UTC>)\n+\n+Inserting data (synchronous)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Start a job loading data asynchronously from a local CSV files.\n+into a new table.  First, create the job locally:\n+\n+.. doctest::\n+\n+   >>> from gcloud import bigquery\n+   >>> client = bigquery.Client()\n+   >>> table = dataset.table(name='person_ages')\n+   >>> with open('/path/to/person_ages.csv') as f:\n+   ...     job = table.load_from_file(f,\n+   ...                                source_format='CSV',\n+   ...                                skip_leading_rows=1\n+   ...                                write_disposition='truncate',\n+   ...                               )  # API request\n+   >>> job.job_id\n+   'e3344fba-09df-4ae0-8337-fddee34b3840'\n+   >>> job.type\n+   'load'\n+   >>> job.created\n+   datetime.datetime(2015, 7, 23, 9, 30, 20, 268260, tzinfo=<UTC>)\n+   >>> job.state\n+   'done'\n+   >>> job.ended\n+   datetime.datetime(2015, 7, 23, 9, 30, 21, 334792, tzinfo=<UTC>)\n+\n+Inserting data (asynchronous)\n+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n+\n+Start a job loading data asynchronously from a set of CSV files, located on\n+GCloud Storage, appending rows into an existing table.  First, create the job\n+locally:\n+\n+.. doctest::\n+\n+   >>> from gcloud import bigquery\n+   >>> client = bigquery.Client()\n+   >>> table = dataset.table(name='person_ages')\n+   >>> job = table.load_from_storage(bucket_name='bucket-name',\n+   ...                               object_name='object-prefix*',","path":"docs/bigquery-usage.rst","position":149,"original_position":149,"commit_id":"84156559b8a1fa06ead8169954c769ab6e428642","original_commit_id":"84156559b8a1fa06ead8169954c769ab6e428642","user":{"login":"tseaver","id":242750,"avatar_url":"https://avatars.githubusercontent.com/u/242750?v=3","gravatar_id":"","url":"https://api.github.com/users/tseaver","html_url":"https://github.com/tseaver","followers_url":"https://api.github.com/users/tseaver/followers","following_url":"https://api.github.com/users/tseaver/following{/other_user}","gists_url":"https://api.github.com/users/tseaver/gists{/gist_id}","starred_url":"https://api.github.com/users/tseaver/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tseaver/subscriptions","organizations_url":"https://api.github.com/users/tseaver/orgs","repos_url":"https://api.github.com/users/tseaver/repos","events_url":"https://api.github.com/users/tseaver/events{/privacy}","received_events_url":"https://api.github.com/users/tseaver/received_events","type":"User","site_admin":false},"body":"Yes (the `gs://bucket_name/object-prefix*` URI selects all the matching objects.","created_at":"2015-07-23T17:41:14Z","updated_at":"2015-07-23T17:41:14Z","html_url":"https://github.com/GoogleCloudPlatform/gcloud-python/pull/1014#discussion_r35349255","pull_request_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/1014","_links":{"self":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/comments/35349255"},"html":{"href":"https://github.com/GoogleCloudPlatform/gcloud-python/pull/1014#discussion_r35349255"},"pull_request":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/1014"}}},"pull_request":{"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/1014","id":40681358,"html_url":"https://github.com/GoogleCloudPlatform/gcloud-python/pull/1014","diff_url":"https://github.com/GoogleCloudPlatform/gcloud-python/pull/1014.diff","patch_url":"https://github.com/GoogleCloudPlatform/gcloud-python/pull/1014.patch","issue_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1014","number":1014,"state":"open","locked":false,"title":"Add usage docs for jobs:  query and load.","user":{"login":"tseaver","id":242750,"avatar_url":"https://avatars.githubusercontent.com/u/242750?v=3","gravatar_id":"","url":"https://api.github.com/users/tseaver","html_url":"https://github.com/tseaver","followers_url":"https://api.github.com/users/tseaver/followers","following_url":"https://api.github.com/users/tseaver/following{/other_user}","gists_url":"https://api.github.com/users/tseaver/gists{/gist_id}","starred_url":"https://api.github.com/users/tseaver/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tseaver/subscriptions","organizations_url":"https://api.github.com/users/tseaver/orgs","repos_url":"https://api.github.com/users/tseaver/repos","events_url":"https://api.github.com/users/tseaver/events{/privacy}","received_events_url":"https://api.github.com/users/tseaver/received_events","type":"User","site_admin":false},"body":"","created_at":"2015-07-23T15:00:16Z","updated_at":"2015-07-23T17:41:14Z","closed_at":null,"merged_at":null,"merge_commit_sha":"55a34b585a592b0fb3fd7e8b35e41186ae5fec98","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/1014/commits","review_comments_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/1014/comments","review_comment_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/comments{/number}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1014/comments","statuses_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/statuses/84156559b8a1fa06ead8169954c769ab6e428642","head":{"label":"tseaver:bigquery-devx-jobs-query_load","ref":"bigquery-devx-jobs-query_load","sha":"84156559b8a1fa06ead8169954c769ab6e428642","user":{"login":"tseaver","id":242750,"avatar_url":"https://avatars.githubusercontent.com/u/242750?v=3","gravatar_id":"","url":"https://api.github.com/users/tseaver","html_url":"https://github.com/tseaver","followers_url":"https://api.github.com/users/tseaver/followers","following_url":"https://api.github.com/users/tseaver/following{/other_user}","gists_url":"https://api.github.com/users/tseaver/gists{/gist_id}","starred_url":"https://api.github.com/users/tseaver/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tseaver/subscriptions","organizations_url":"https://api.github.com/users/tseaver/orgs","repos_url":"https://api.github.com/users/tseaver/repos","events_url":"https://api.github.com/users/tseaver/events{/privacy}","received_events_url":"https://api.github.com/users/tseaver/received_events","type":"User","site_admin":false},"repo":{"id":23322104,"name":"gcloud-python","full_name":"tseaver/gcloud-python","owner":{"login":"tseaver","id":242750,"avatar_url":"https://avatars.githubusercontent.com/u/242750?v=3","gravatar_id":"","url":"https://api.github.com/users/tseaver","html_url":"https://github.com/tseaver","followers_url":"https://api.github.com/users/tseaver/followers","following_url":"https://api.github.com/users/tseaver/following{/other_user}","gists_url":"https://api.github.com/users/tseaver/gists{/gist_id}","starred_url":"https://api.github.com/users/tseaver/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/tseaver/subscriptions","organizations_url":"https://api.github.com/users/tseaver/orgs","repos_url":"https://api.github.com/users/tseaver/repos","events_url":"https://api.github.com/users/tseaver/events{/privacy}","received_events_url":"https://api.github.com/users/tseaver/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/tseaver/gcloud-python","description":"Google Cloud Python Client Library","fork":true,"url":"https://api.github.com/repos/tseaver/gcloud-python","forks_url":"https://api.github.com/repos/tseaver/gcloud-python/forks","keys_url":"https://api.github.com/repos/tseaver/gcloud-python/keys{/key_id}","collaborators_url":"https://api.github.com/repos/tseaver/gcloud-python/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/tseaver/gcloud-python/teams","hooks_url":"https://api.github.com/repos/tseaver/gcloud-python/hooks","issue_events_url":"https://api.github.com/repos/tseaver/gcloud-python/issues/events{/number}","events_url":"https://api.github.com/repos/tseaver/gcloud-python/events","assignees_url":"https://api.github.com/repos/tseaver/gcloud-python/assignees{/user}","branches_url":"https://api.github.com/repos/tseaver/gcloud-python/branches{/branch}","tags_url":"https://api.github.com/repos/tseaver/gcloud-python/tags","blobs_url":"https://api.github.com/repos/tseaver/gcloud-python/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/tseaver/gcloud-python/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/tseaver/gcloud-python/git/refs{/sha}","trees_url":"https://api.github.com/repos/tseaver/gcloud-python/git/trees{/sha}","statuses_url":"https://api.github.com/repos/tseaver/gcloud-python/statuses/{sha}","languages_url":"https://api.github.com/repos/tseaver/gcloud-python/languages","stargazers_url":"https://api.github.com/repos/tseaver/gcloud-python/stargazers","contributors_url":"https://api.github.com/repos/tseaver/gcloud-python/contributors","subscribers_url":"https://api.github.com/repos/tseaver/gcloud-python/subscribers","subscription_url":"https://api.github.com/repos/tseaver/gcloud-python/subscription","commits_url":"https://api.github.com/repos/tseaver/gcloud-python/commits{/sha}","git_commits_url":"https://api.github.com/repos/tseaver/gcloud-python/git/commits{/sha}","comments_url":"https://api.github.com/repos/tseaver/gcloud-python/comments{/number}","issue_comment_url":"https://api.github.com/repos/tseaver/gcloud-python/issues/comments{/number}","contents_url":"https://api.github.com/repos/tseaver/gcloud-python/contents/{+path}","compare_url":"https://api.github.com/repos/tseaver/gcloud-python/compare/{base}...{head}","merges_url":"https://api.github.com/repos/tseaver/gcloud-python/merges","archive_url":"https://api.github.com/repos/tseaver/gcloud-python/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/tseaver/gcloud-python/downloads","issues_url":"https://api.github.com/repos/tseaver/gcloud-python/issues{/number}","pulls_url":"https://api.github.com/repos/tseaver/gcloud-python/pulls{/number}","milestones_url":"https://api.github.com/repos/tseaver/gcloud-python/milestones{/number}","notifications_url":"https://api.github.com/repos/tseaver/gcloud-python/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/tseaver/gcloud-python/labels{/name}","releases_url":"https://api.github.com/repos/tseaver/gcloud-python/releases{/id}","created_at":"2014-08-25T17:19:33Z","updated_at":"2015-04-10T19:42:56Z","pushed_at":"2015-07-23T17:29:23Z","git_url":"git://github.com/tseaver/gcloud-python.git","ssh_url":"git@github.com:tseaver/gcloud-python.git","clone_url":"https://github.com/tseaver/gcloud-python.git","svn_url":"https://github.com/tseaver/gcloud-python","homepage":"http://googlecloudplatform.github.io/gcloud-python/","size":9632,"stargazers_count":1,"watchers_count":1,"language":"Python","has_issues":false,"has_downloads":true,"has_wiki":true,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":1,"default_branch":"master"}},"base":{"label":"GoogleCloudPlatform:master","ref":"master","sha":"49703d9c662ecd99bb5869833566e9b06fb44ae6","user":{"login":"GoogleCloudPlatform","id":2810941,"avatar_url":"https://avatars.githubusercontent.com/u/2810941?v=3","gravatar_id":"","url":"https://api.github.com/users/GoogleCloudPlatform","html_url":"https://github.com/GoogleCloudPlatform","followers_url":"https://api.github.com/users/GoogleCloudPlatform/followers","following_url":"https://api.github.com/users/GoogleCloudPlatform/following{/other_user}","gists_url":"https://api.github.com/users/GoogleCloudPlatform/gists{/gist_id}","starred_url":"https://api.github.com/users/GoogleCloudPlatform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/GoogleCloudPlatform/subscriptions","organizations_url":"https://api.github.com/users/GoogleCloudPlatform/orgs","repos_url":"https://api.github.com/users/GoogleCloudPlatform/repos","events_url":"https://api.github.com/users/GoogleCloudPlatform/events{/privacy}","received_events_url":"https://api.github.com/users/GoogleCloudPlatform/received_events","type":"Organization","site_admin":false},"repo":{"id":16316451,"name":"gcloud-python","full_name":"GoogleCloudPlatform/gcloud-python","owner":{"login":"GoogleCloudPlatform","id":2810941,"avatar_url":"https://avatars.githubusercontent.com/u/2810941?v=3","gravatar_id":"","url":"https://api.github.com/users/GoogleCloudPlatform","html_url":"https://github.com/GoogleCloudPlatform","followers_url":"https://api.github.com/users/GoogleCloudPlatform/followers","following_url":"https://api.github.com/users/GoogleCloudPlatform/following{/other_user}","gists_url":"https://api.github.com/users/GoogleCloudPlatform/gists{/gist_id}","starred_url":"https://api.github.com/users/GoogleCloudPlatform/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/GoogleCloudPlatform/subscriptions","organizations_url":"https://api.github.com/users/GoogleCloudPlatform/orgs","repos_url":"https://api.github.com/users/GoogleCloudPlatform/repos","events_url":"https://api.github.com/users/GoogleCloudPlatform/events{/privacy}","received_events_url":"https://api.github.com/users/GoogleCloudPlatform/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/GoogleCloudPlatform/gcloud-python","description":"Google Cloud Client Library for Python","fork":false,"url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python","forks_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/forks","keys_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/keys{/key_id}","collaborators_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/teams","hooks_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/hooks","issue_events_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/events{/number}","events_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/events","assignees_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/assignees{/user}","branches_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/branches{/branch}","tags_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/tags","blobs_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/git/refs{/sha}","trees_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/git/trees{/sha}","statuses_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/statuses/{sha}","languages_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/languages","stargazers_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/stargazers","contributors_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/contributors","subscribers_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/subscribers","subscription_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/subscription","commits_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/commits{/sha}","git_commits_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/git/commits{/sha}","comments_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/comments{/number}","issue_comment_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/comments{/number}","contents_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/contents/{+path}","compare_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/compare/{base}...{head}","merges_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/merges","archive_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/downloads","issues_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues{/number}","pulls_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls{/number}","milestones_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/milestones{/number}","notifications_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/labels{/name}","releases_url":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/releases{/id}","created_at":"2014-01-28T15:51:47Z","updated_at":"2015-07-22T17:10:14Z","pushed_at":"2015-07-23T17:34:22Z","git_url":"git://github.com/GoogleCloudPlatform/gcloud-python.git","ssh_url":"git@github.com:GoogleCloudPlatform/gcloud-python.git","clone_url":"https://github.com/GoogleCloudPlatform/gcloud-python.git","svn_url":"https://github.com/GoogleCloudPlatform/gcloud-python","homepage":"https://googlecloudplatform.github.io/gcloud-python/","size":37534,"stargazers_count":183,"watchers_count":183,"language":"Python","has_issues":true,"has_downloads":true,"has_wiki":true,"has_pages":true,"forks_count":99,"mirror_url":null,"open_issues_count":97,"forks":99,"open_issues":97,"watchers":183,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/1014"},"html":{"href":"https://github.com/GoogleCloudPlatform/gcloud-python/pull/1014"},"issue":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1014"},"comments":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/issues/1014/comments"},"review_comments":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/1014/comments"},"review_comment":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/pulls/1014/commits"},"statuses":{"href":"https://api.github.com/repos/GoogleCloudPlatform/gcloud-python/statuses/84156559b8a1fa06ead8169954c769ab6e428642"}}}}