{"action":"created","issue":{"url":"https://api.github.com/repos/cockroachdb/docs/issues/2762","repository_url":"https://api.github.com/repos/cockroachdb/docs","labels_url":"https://api.github.com/repos/cockroachdb/docs/issues/2762/labels{/name}","comments_url":"https://api.github.com/repos/cockroachdb/docs/issues/2762/comments","events_url":"https://api.github.com/repos/cockroachdb/docs/issues/2762/events","html_url":"https://github.com/cockroachdb/docs/pull/2762","id":307434018,"number":2762,"title":"Enhance various statements and diagrams","user":{"login":"knz","id":642886,"avatar_url":"https://avatars3.githubusercontent.com/u/642886?v=4","gravatar_id":"","url":"https://api.github.com/users/knz","html_url":"https://github.com/knz","followers_url":"https://api.github.com/users/knz/followers","following_url":"https://api.github.com/users/knz/following{/other_user}","gists_url":"https://api.github.com/users/knz/gists{/gist_id}","starred_url":"https://api.github.com/users/knz/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/knz/subscriptions","organizations_url":"https://api.github.com/users/knz/orgs","repos_url":"https://api.github.com/users/knz/repos","events_url":"https://api.github.com/users/knz/events{/privacy}","received_events_url":"https://api.github.com/users/knz/received_events","type":"User","site_admin":false},"labels":[{"id":808984040,"url":"https://api.github.com/repos/cockroachdb/docs/labels/in%20progress","name":"in progress","color":"ededed","default":false}],"state":"open","locked":false,"assignee":null,"assignees":[],"milestone":null,"comments":10,"created_at":"2018-03-21T22:02:17Z","updated_at":"2018-03-25T21:10:01Z","closed_at":null,"author_association":"OWNER","pull_request":{"url":"https://api.github.com/repos/cockroachdb/docs/pulls/2762","html_url":"https://github.com/cockroachdb/docs/pull/2762","diff_url":"https://github.com/cockroachdb/docs/pull/2762.diff","patch_url":"https://github.com/cockroachdb/docs/pull/2762.patch"},"body":"Fixes #2719.\r\n\r\nFixes #2519.\r\n\r\n**tl;dr**: fix confusion, better document joins, fix upsert/delete/insert/update.\r\n\r\nPrior to this patch, the documentation was confusing \"SELECT\r\nstatements\" and \"selection clauses\". This confusion was most visible in the documentation for INSERT and UPSERT, which incorrectly specified that these statements take a selection clause as operand, whereas they support much more than that.\r\n\r\nThe documentation was also incorrectly listing set operations (EXCEPT/UNION etc) as operators of SELECT in particular, whereas they actually work also with any selection clause.\r\n\r\nThe root cause of this sorry state of affairs was caused by a single\r\nmisconception: there is really no such thing as a \"SELECT statement\"\r\nin the SQL grammar; instead there are various relational expressions\r\nand operators, and selection clauses are just a particular instance of relational expressions.\r\n\r\nThis patch enhances this situation as follows:\r\n\r\n- The page about a \"SELECT statement\" is deleted. It is replaced by a\r\n  page titled \"Simple SELECT clause\", to properly highlight it is\r\n  merely an instance of a selection clause (albeit with a reminder\r\n  that it happens to also be valid as standalone statement).\r\n\r\n- To ensure the basic SELECT syntax remains the \"main SELECT doc page\"\r\n  for newcomers, the top-level links in navigation for the `SELECT`\r\n  keyword are changed to point to the page on the simple SELECT\r\n  clause.\r\n\r\n- A new page \"Relational Expressions\" is introduced, which explains\r\n  properly the concept of \"Statement-like Query\". The pages about\r\n  other statements that require a statement-like query are modified to\r\n  point to this new page.\r\n\r\n- The difference between \"table expressions\", \"selection clauses\" and\r\n  \"statement-like queries\" is repeatedly clarified in numerous places,\r\n  to ensure that clarity is pervasively maintained throughout the\r\n  docs.\r\n\r\nAdditionally, the syntax diagrams for all these constructs are updated to more accurately reflect reality. Some more documentation for the various `JOIN` operators is added.\r\n\r\nTo review this patch, the reviewer is invited to first proceed in a\r\nholistic manner and navigate the result of the changes with the eyes\r\nof a newcomer:\r\n\r\n1. Land on the \"Simple SELECT clause\" page; ensure that it makes\r\n   sense, including its simplified syntax diagram.\r\n\r\n2. Check out the page on \"Table Expressions\", which documents what can\r\n   fit in the FROM clause of a simple SELECT clause. Check that it\r\n   makes sense, including the new syntax diagrams.\r\n\r\n2. Check the docs for INSERT/UPDATE/UPSERT/DELETE and check they make\r\n   sense, including the new syntax diagrams.\r\n\r\n3. Navigate to the page on \"Relational Expressions\" and check that it\r\n   makes sense, including the new syntax diagrams.\r\n\r\n4. Review the new page \"Limiting Query Results\" linked from there.\r\n\r\nOnce the reviewer satisfies themselves that the relationship between\r\nthe pages and the syntax diagrams make sense, the line-by-line diff\r\ncan be reviewed for further edits."},"comment":{"url":"https://api.github.com/repos/cockroachdb/docs/issues/comments/376003760","html_url":"https://github.com/cockroachdb/docs/pull/2762#issuecomment-376003760","issue_url":"https://api.github.com/repos/cockroachdb/docs/issues/2762","id":376003760,"user":{"login":"cockroach-teamcity","id":20559710,"avatar_url":"https://avatars0.githubusercontent.com/u/20559710?v=4","gravatar_id":"","url":"https://api.github.com/users/cockroach-teamcity","html_url":"https://github.com/cockroach-teamcity","followers_url":"https://api.github.com/users/cockroach-teamcity/followers","following_url":"https://api.github.com/users/cockroach-teamcity/following{/other_user}","gists_url":"https://api.github.com/users/cockroach-teamcity/gists{/gist_id}","starred_url":"https://api.github.com/users/cockroach-teamcity/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/cockroach-teamcity/subscriptions","organizations_url":"https://api.github.com/users/cockroach-teamcity/orgs","repos_url":"https://api.github.com/users/cockroach-teamcity/repos","events_url":"https://api.github.com/users/cockroach-teamcity/events{/privacy}","received_events_url":"https://api.github.com/users/cockroach-teamcity/received_events","type":"User","site_admin":false},"created_at":"2018-03-25T21:10:01Z","updated_at":"2018-03-25T21:10:01Z","author_association":"MEMBER","body":"http://cockroach-docs-review.s3-website-us-east-1.amazonaws.com/790a73da4a738ec5ab5c3de7c6f4a779fc6a0d6a/"}}
{"actor":{"display_login":"cockroach-teamcity"}}