How to correctly read documentation from an SQL command?

Question

I was studying the concept of transactions and as always the reference was the documentation of Microsoft itself (in the case for the products of the same).

In the link below there is the documentation of the BEGIN TRANSACTION command.

https://docs.microsoft.com/pt-br/sql/t-sql/language-elements/begin-transaction-transact-sql?view=sql-server-2017

The first line of the syntax block is: BEGIN { TRAN | TRANSACTION }

The use of "{}" keys represents what? Does the use of pipe "|" represent that I can choose to use the TRAN or TRANSACTION command? Use of "[]" brackets represents optional command?

Answer 1

The notation for documentation means the following:

{ } or < >: what’s inside of keys is obligatory, should be used

{ x | y } or < x | y >: an option, x or y, shall be chosen obligatory

[ ]: what’s inside the brackets is optional, may or may not be using

Here more details about the notation used in the syntax: Sintax Notation

Analyzing your example:

1 BEGIN { TRAN | TRANSACTION }   
2     [ { transaction_name | @tran_name_variable }  
3       [ WITH MARK [ 'description' ] ]  
4     ]  
5 [ ; ] 

1. The command begins with BEGIN and must obligatorily be followed by one of the options or TRAN (abridged version) or TRANSACTION
2. The [ indicates that it is optional declare or not variable
3. IS optional declare or not WITH MARK and still is optional the description
4. This bracket closes what was opened on line 2
5. IS optional close with the ;

Another example is the SELECT command:

SELECT [ ALL | DISTINCT ]   
    [TOP ( expression ) [PERCENT] [ WITH TIES ] ]   
    < select_list >   
    [ INTO new_table ]   
    [ FROM { <table_source> } [ ,...n ] ]   
    [ WHERE <search_condition> ]   
    [ <GROUP BY> ]   
    [ HAVING < search_condition > ]  

See that in command SELECT, use ALL or DISTINCT is optional, as well as INTO and WHERE for example, but the < select_list > is mandatory, i.e., the list of fields, variables or values of the command SELECT

A simple SELECT 1 so it works, based on the syntax description above :)

Answer 2

Keys are a form of grouping, meaning that everything in there is one thing, it’s like parentheses in a normal programming expression that eliminates ambiguity. So obviously inside has more than one element, after all it would not have why to group only one thing. In this case has something that should choose why has the | (is an OR), therefore it is one or the other, and in this specific case it allows the complete form of the word or the abbreviated form.

The brackets actually indicate that something is optional and if not using does not affect the syntax, it can affect the semantics in most cases, but in SQL there is a lot of case that is only syntax simplification, the same up there could be documented like this:

BEGIN TRAN[SACTION]

I put in the Github for future reference.

But it is not common to do so, it is a little less clear.