.. highlight:: none .. _storm-ref-syntax: Storm Reference - Document Syntax Conventions ============================================= This section covers the following important conventions used within the Storm Reference Documents: - `Storm and Layers`_ - `Storm Syntax Conventions`_ - `Usage Statements vs. Specific Storm Queries`_ - `Type-Specific Behavior`_ - `Whitespace`_ Storm and Layers ---------------- **The Storm Reference documentation provides basic syntax examples that assume a simple Storm environment - that is, a Cortex with a single Layer.** For multi-Layer Cortexes, the effects of specific Storm commands - particularly data modification commands - may vary based on the specific arrangement of read / write Layers, the Layer in which the command is executed, and the permissions of the user. Storm Syntax Conventions ------------------------ The Storm Reference documentation provides numerous examples of both abstract Storm syntax (usage statements) and specific Storm queries. The following conventions are used for Storm **usage statements:** - Items that must be entered literally on the command line are in **bold.** These items include command names and literal characters. - Items that represent "variables" that must be replaced with a name or value are placed within angle brackets ( ``< >`` ) in *italics*. Most "variables" are self-explanatory, however a few commonly used variable terms are defined here for convenience: - *

* refers to a form / node primary property, such as ``inet:fqdn``. - ** refers to the value of a primary property, such as ``woot.com`` in ``inet:fqdn=woot.com``. - ** refers to a node secondary property (including universal properties) such as ``inet:ipv4:asn`` or ``inet:ipv4.created``. - ** refers to the value of a secondary property, such as ``4808`` in ``inet:ipv4:asn=4808``. - ** refers to a Storm query. - ** refers to a Storm query whose results contain the specified form(s) - ** refers to a tag (``#sometag`` as opposed to a ``syn:tag`` form). - **Bold brackets** are literal characters. Parameters enclosed in non-bolded brackets are optional. - Parameters **not** enclosed in brackets are required. - A vertical bar signifies that you choose only one parameter. For example: - ``a | b`` indicates that you must choose a or b. - ``[ a | b ]`` indicates that you can choose a, b, or nothing (the non-bolded brackets indicate the parameter is optional). - Ellipses ( `...` ) signify the parameter can be repeated on the command line. - The ``storm`` command that must precede a Storm query is assumed and is omitted from examples. **Example:** **[** ** **=** ** [ **:** ** **=** ** ... ] **]** The Storm query above adds a new node. - The outer brackets are in **bold** and are required literal characters to specify a data modification (add) operation. Similarly, the equals signs are in **bold** to indicate literal characters. - ** and ** would need to be replaced by the specific form (such as ``inet:ipv4``) and primary property value (such as ``1.2.3.4``) for the node being created. - The inner brackets are not bolded and indicate that one or more secondary properties can **optionally** be specified. - ** and ** would need to be replaced by the specific secondary property and value to add to the node, such as ``:loc = us``. - The ellipsis ( ``...`` ) indicate that additional secondary properties can optionally be specified. Usage Statements vs. Specific Storm Queries ------------------------------------------- Examples of specific queries represent fully literal input, but are not shown in bold for readability. For example: **Usage statement:** **[** ** **=** ** [ **:** ** **=** ** ...] **]** **Example query:** [ inet:ipv4 = 1.2.3.4 :loc = us ] Type-Specific Behavior ---------------------- Some data types within the Synapse data model have been optimized in ways that impact their behavior within Storm queries (e.g., how types can be input, lifted, filtered, etc.) See :ref:`storm-ref-type-specific` for details. Whitespace ---------- Whitespace may be used in the examples for formatting and readability. See the section Synapse Tools - Cmdr on :ref:`whitespace` for how whitespace is used in the Synapse CLI, including within the Storm command.