Introduction
Following is a list of the styles we standardize to make SQL grammar easy and fast to read for users. To see examples of how these styles look in documentation, visit the SAP HANA Cloud SQL Reference Guide.
Syntax Section
Likely the most complex feature of a statement or function topic, the is an abbreviated Backus-Naur Form (BNF) that gives the layout of the statement and its clauses.
We do this because full BNF representations can be several pages long, and difficult to follow because they exhaustively iterate through all possibilities. By compacting the grammar enough to fit at the top of a topic, we deliver an at-a-glance understanding of the structure of the grammar.
Other styles that we apply—for example, consistent bracketing, casing, whitespace, and indenting—convey even more information to users about:
- the location/general order of the major clauses and options
- the relationship between the various clauses, sub-clauses, and options
Here is a list of conventions we apply:
- SQL keywords such as clauses and sub-clauses are capitalized (e.g. CREATE INDEX). The software doesn't require caps, but using them helps the user know that these are the actual SQL keywords used by the software.
- Things that users must type - (commas, quotes) are left plain.
- Spaces between and around everything (including brackets and braces) make the syntax block easier for the user to scan. The software doesn't require the spacing (they are ignored), its purely to help the user unpack what they are seeing. Rare exceptions where spaces would break the parser's processing, for example in HTML strings, should be avoided in the syntax.
- ( ) - These parentheses are an actual part of the SQL grammar. The user must type them.
- { } - Curly braces denote a set of options, separated by the pipe symbol (|). The user picks one element from the set of elements when creating their statement. The user doesn't include the braces or pipe symbol.
- [ ] - Square brackets denote an optional part of the syntax. The user doesn't include these brackets.
- [,...] - Comma and ellipsis within square brackets denotes 'one or more' of an element are allowed, separated by commas. For example: [ name=value [,...] ] suggests that you can optionally specify one or more name/value pairs.
- [...] - Ellipsis within square brackets, without a comma, denotes 'one or more' of an element are allowed, with no comma required between them.
- Use consistent whitespace to denote the nestedness/relationship of clauses relative to their surrounding clauses. Users rely on this visual cue to understand things like 'is this clause a peer to the previous clause or a sub-clause of the previous clause. If you aren't sure of the relationship between the clauses, ask your engineer. Without proper nesting, it's quite difficult to understand the relationship between elements in a block of SQL.
- variables – Variables are placeholders in the grammar where users will specify their own values. Give your variables a clear name to help users know what they're for, that accessibility screen readers won't mangle, and separate the words with underscores (e.g, <city_name>, not <cname>) ). It's ok to use different variables than the cryptic variable names engineering picks when describing their changes.
- See also: SQL Notation Conventions - SAP Help Portal.
Example 1: CREATE INDEX Statement (found here)
Syntax Elements
- This section is always a <parml>, with each clause from the main syntax block being a <plentry>. For sub-clauses and options within the <plentry>, use <dl>.
- For titles of the bullets, include the SQL keywords and associated variable when possible. For example, use TIME <timestamp> instead of just TIME or <time_stamp>.
- Don't include full examples of a clause within these bullets. Instead, use exemplary snippets and put full examples in the Examples section.
- No inline links in these bullets or anywhere in the guide. Tell the user what to look for in the other guide using words, and then put the link in the Related Information section.
- You can use conkeyref bullets between topics, provided you use wording suitable for both contexts. Examples are: CREATE and ALTER versions of a statement. Include a draft-comment that states that the content is reused in multiple locations as there is no other way to know that when you update the content.
- In-topic links are links that take you from one place to another in the topic. However, use them sparingly. Refer to the ALTER TABLE statement to see how they must be formatted.
- If not specified, include information about defaults. If you don't know the default behavior, ask the engineers.
Permissions Section
- Refer to at least 3 other topics to get a hang of the wording.
Example: "You must have the XYZ and ABC privileges." - Do not start the sentence with your own choice of wording such as "You require the XYZ privilege". ("You require the" is incorrect anyway. It's actually the s/w doing the requiring!)
Examples Section
Make sure that your examples follow the SQL Notation guidelines listed above.
Also, use copy, pastable, and runnable examples, not fictitious ones for inspiration. If necessary, ask the engineers for simple and runnable examples. However, if the example looks too long or complicated to include, just switch excerpts from a working one. For example, when you have to create a remote source to show how to use options on a remote source. In either case, be sure to apply the style guidelines to the examples, with the exception of the white-spacing guidelines.
SQL/SQLScript Announcement Process
SQL Announcement emails alert downstream stakeholder teams (like UA) that a change to the SQL and/or SQLScript grammar has been merged to the codeline. For information about the process, go to SQL/SQLScript Announcement Process.