API di DocumentDB per Azure Cosmos DB: riferimento per la sintassi SQLAzure Cosmos DB DocumentDB API: SQL syntax reference

L'API di DocumentDB per Azure Cosmos DB supporta l'esecuzione di query sui documenti usando un linguaggio SQL (Structured Query Language) familiare come una grammatica per i documenti JSON gerarchici senza richiedere uno schema esplicito o la creazione di indici secondari.The Azure Cosmos DB DocumentDB API supports querying documents using a familiar SQL (Structured Query Language) like grammar over hierarchical JSON documents without requiring explicit schema or creation of secondary indexes. Questo argomento indica la documentazione di riferimento per il linguaggio delle query SQL dell'API di DocumentDB.This topic provides reference documentation for the DocumentDB API SQL query language.

Per una procedura dettagliata sul linguaggio delle query SQL dell'API di DocumentDB, vedere l'articolo relativo alle query SQL per l'API di DocumentDB di Azure Cosmos DB.For a walkthrough of the DocumentDB API SQL query language, see SQL queries for Azure Cosmos DB DocumentDB API.

Consigliamo di visitare anche il Query Playground in cui è possibile provare Azure Cosmos DB ed eseguire query SQL usando il set di dati disponibile.We also invite you to visit the Query Playground where you can try Azure Cosmos DB and run SQL queries against our dataset.

Query SELECTSELECT query

Recupera i documenti JSON dal database.Retrieves JSON documents from the database. Supporta la valutazione delle espressioni, le proiezioni, il filtraggio e i join.Supports expression evaluation, projections, filtering and joins. Le convenzioni usate per descrivere le istruzioni SELECT sono riportate nella sezione relativa alle convenzioni della sintassi.The conventions used for describing the SELECT statements are tabulated in the Syntax conventions section.

SintassiSyntax

<select_query> ::=  
SELECT <select_specification>   
    [ FROM <from_specification>]   
    [ WHERE <filter_condition> ]  
    [ ORDER BY <sort_specification> ]  

OsservazioniRemarks

Per i dettagli su ogni clausola, vedere le sezioni seguenti:See following sections for details on each clause:

Le clausole nell'istruzione SELECT devono essere ordinate come indicato sopra.The clauses in the SELECT statement must be ordered as shown above. Una clausola facoltativa può essere omessa.Any one of the optional clauses can be omitted. Ma se si usano clausole facoltative, è necessario specificarle nell'ordine corretto.But when optional clauses are used, they must appear in the right order.

Ordine di elaborazione logico dell'istruzione SELECTLogical Processing Order of the SELECT statement

L'ordine in cui vengono elaborate clausole è:The order in which clauses are processed is:

  1. Clausola FROMFROM clause
  2. Clausola WHEREWHERE clause
  3. Clausola ORDER BYORDER BY clause
  4. Clausola SELECTSELECT clause

Si noti che l'ordine è diverso da quello in cui appaiono nella sintassi.Note that this is different from the order in which they appear in the syntax. L'ordinamento è tale che tutti i nuovi simboli introdotti da una clausola elaborata sono visibili e possono essere usati nelle clausole elaborate successivamente.The ordering is such that all new symbols introduced by a processed clause are visible and can be used in clauses processed later. Ad esempio, gli alias dichiarati in una clausola FROM sono accessibili nelle clausole WHERE e SELECT.For instance, aliases declared in a FROM clause are accessible in WHERE and SELECT clauses.

Spazi vuoti e commentiWhitespace characters and comments

Tutti i caratteri di spazio vuoto che non fanno parte di una stringa o un identificatore delimitato non fanno parte della grammatica del linguaggio e vengono ignorati durante l'analisi.All white space characters which are not part of a quoted string or quoted identifier are not part of the language grammar and are ignored during parsing.

Il linguaggio di query supporta i commenti in stile T-SQL comeThe query language supports T-SQL style comments like

  • istruzione SQL -- comment text [newline]SQL Statement -- comment text [newline]

Anche se i commenti e gli spazi vuoti non hanno alcun significato nella grammatica, devono essere usati per separare i token.While whitespace characters and comments do not have any significance in the grammar, they must be used to separate tokens. Ad esempio: -1e5 è un token numero singolo, mentre : – 1 e5 è un token meno seguito dal numero 1 e dall'identificatore e5.For instance: -1e5 is a single number token, while: – 1 e5 is a minus token followed by number 1 and identifier e5.

Clausola SELECTSELECT clause

Le clausole nell'istruzione SELECT devono essere ordinate come indicato sopra.The clauses in the SELECT statement must be ordered as shown above. Una clausola facoltativa può essere omessa.Any one of the optional clauses can be omitted. Ma se si usano clausole facoltative, è necessario specificarle nell'ordine corretto.But when optional clauses are used, they must appear in the right order.

SintassiSyntax

SELECT <select_specification>  

<select_specification> ::=   
      '*'   
      | <object_property_list>   
      | VALUE <scalar_expression> [[ AS ] value_alias]  

<object_property_list> ::=   
{ <scalar_expression> [ [ AS ] property_alias ] } [ ,...n ]  

ArgomentiArguments

<select_specification>

Proprietà o valore da selezionare per il set di risultati.Properties or value to be selected for the result set.

'*'

Specifica che il valore deve essere recuperato senza apportare alcuna modifica.Specifies that the value should be retrieved without making any changes. In particolare, se il valore elaborato è un oggetto, tutte le proprietà verranno recuperate.Specifically if the processed value is an object, all properties will be retrieved.

<object_property_list>

Specifica l'elenco di proprietà da recuperare.Specifies the list of properties to be retrieved. Ogni valore restituito sarà un oggetto con le proprietà specificate.Each returned value will be an object with the properties specified.

VALUE

Specifica che deve essere recuperato il valore JSON anziché l'oggetto JSON completo.Specifies that the JSON value should be retrieved instead of the complete JSON object. A differenza di <property_list> non esegue il wrapping del valore previsto in un oggetto.This, unlike <property_list> does not wrap the projected value in an object.

<scalar_expression>

Espressione che rappresenta il valore da calcolare.Expression representing the value to be computed. Vedere la sezione Espressioni scalari per informazioni dettagliate.See Scalar expressions section for details.

OsservazioniRemarks

La sintassi di SELECT * è valida solo se la clausola FROM ha dichiarato esattamente un alias.The SELECT * syntax is only valid if FROM clause has declared exactly one alias. SELECT * offre una proiezione dell'identità, che può essere utile se non è necessaria alcuna proiezione.SELECT * provides an identity projection, which can be useful if no projection is needed. SELECT * è valida solo se viene specificata la clausola FROM e se viene introdotta solo una singola origine di input.SELECT * is only valid if FROM clause is specified and introduced only a single input source.

Si noti che SELECT <select_list> e SELECT * sono "zucchero sintattico" e può essere espressi in alternativa usando semplici istruzioni SELECT, come illustrato di seguito.Note that SELECT <select_list> and SELECT * are "syntactic sugar" and can be alternatively expressed by using simple SELECT statements as shown below.

  1. SELECT * FROM ... AS from_alias ...

    Equivale a:is equivalent to:

    SELECT from_alias FROM ... AS from_alias ...

  2. SELECT <expr1> AS p1, <expr2> AS p2,..., <exprN> AS pN [other clauses...]

    Equivale a:is equivalent to:

    SELECT VALUE { p1: <expr1>, p2: <expr2>, ..., pN: <exprN> }[other clauses...]

Vedere ancheSee Also

Espressioni scalariScalar expressions
Clausola SELECTSELECT clause

Clausola FROMFROM clause

Specifica l'origine o le origini unite in join.Specifies the source or joined sources. La clausola FROM è facoltativa.The FROM clause is optional. Se non viene specificata, le altre clausole verranno comunque eseguite come se la clausola FROM specificasse un singolo documento.If not specified, other clauses will still be executed as if FROM clause provided a single document.

SintassiSyntax

FROM <from_specification>  

<from_specification> ::=   
        <from_source> {[ JOIN <from_source>][,...n]}  

<from_source> ::=   
          <collection_expression> [[AS] input_alias]  
        | input_alias IN <collection_expression>  

<collection_expression> ::=   
        ROOT   
     | collection_name  
     | input_alias  
     | <collection_expression> '.' property_name  
     | <collection_expression> '[' "property_name" | array_index ']'  

ArgomentiArguments

<from_source>

Specifica un'origine dati, con o senza un alias.Specifies a data source, with or without an alias. Se non viene specificato, l'alias verrà dedotto da <collection_expression> usando le seguenti regole:If alias is not specified, it will be inferred from the <collection_expression> using following rules:

  • Se l'espressione è un nome di raccolta, come alias verrà usato il nome della raccolta.If the expression is a collection_name, then collection_name will be used as an alias.

  • Se l'espressione è <collection_expression> seguito da un nome di proprietà, come alias verrà usato il nome della proprietà.If the expression is <collection_expression>, then property_name, then property_name will be used as an alias. Se l'espressione è un nome di raccolta, come alias verrà usato il nome della raccolta.If the expression is a collection_name, then collection_name will be used as an alias.

AS input_aliasAS input_alias

Specifica che l'oggetto input_alias è un set di valori restituiti dall'espressione di raccolta sottostante.Specifies that the input_alias is a set of values returned by the underlying collection expression.

input_alias INinput_alias IN

Specifica che input_alias deve rappresentare il set di valori ottenuto eseguendo l'iterazione su tutti gli elementi di ogni matrice restituita dall'espressione di raccolta sottostante.Specifies that the input_alias should represent the set of values obtained by iterating over all array elements of each array returned by the underlying collection expression. Tutti i valori restituiti dall'espressione di raccolta sottostante che non sono matrici vengono ignorati.Any value returned by underlying collection expression that is not an array is ignored.

<collection_expression>

Specifica l'espressione di raccolta da usare per recuperare i documenti.Specifies the collection expression to be used to retrieve the documents.

ROOT

Specifica che il documento deve essere recuperato dalla raccolta predefinita attualmente connessa.Specifies that document should be retrieved from the default, currently connected collection.

collection_name

Specifica che il documento deve essere recuperato dalla raccolta specificata.Specifies that document should be retrieved from the provided collection. Il nome della raccolta deve corrispondere al nome della raccolta a cui si è attualmente connessi.The name of the collection must match the name of the collection currently connected to.

input_alias

Specifica che il documento deve essere recuperato dall'altra origine definita dall'alias indicato.Specifies that document should be retrieved from the other source defined by the provided alias.

<collection_expression> '.' property_

Specifica che il documento deve essere recuperato eseguendo l'accesso alla proprietà property_name o all'elemento di matrice array_index per tutti i documenti recuperati dall'espressione di raccolta specificata.Specifies that document should be retrieved by accessing the property_name property or array_index array element for all documents retrieved by specified collection expression.

<collection_expression> '[' "property_name" | array_index ']'

Specifica che il documento deve essere recuperato eseguendo l'accesso alla proprietà property_name o all'elemento di matrice array_index per tutti i documenti recuperati dall'espressione di raccolta specificata.Specifies that document should be retrieved by accessing the property_name property or array_index array element for all documents retrieved by specified collection expression.

OsservazioniRemarks

Tutti gli alias specificati o dedotti in <from_source>( devono essere univoci.All aliases provided or inferred in the <from_source>(s) must be unique. La sintassi <collection_expression>.nome proprietà equivale a <collection_expression>' ['"property_name"']'.The Syntax <collection_expression>.property_name is the same as <collection_expression>' ['"property_name"']'. Tuttavia, la seconda sintassi può essere usata se un nome di proprietà contiene un carattere non identificatore.However, the latter syntax can be used if a property name contains a non-identifier characters.

Proprietà mancanti, elementi di matrice mancanti, gestione dei valori non definitaMissing properties, missing array elements, undefined values handling

Se un'espressione di raccolta accede alle proprietà o agli elementi di matrice e il valore non esiste, tale valore verrà ignorato e non elaborato ulteriormente.If a collection expression accesses properties or array elements and that value does not exist, that value will be ignored and not processed further.

Definizione dell'ambito per il contesto dell'espressione di raccoltaCollection expression context scoping

Un'espressione di raccolta può avere come ambito una raccolta o un documento:A collection expression may be collection-scoped or document-scoped:

  • Un'espressione ha un ambito raccolta se l'origine dell'espressione di raccolta sottostante è ROOT o collection_name.An expression is collection-scoped, if the underlying source of the collection expression is either ROOT or collection_name. Un'espressione di questo tipo rappresenta un set di documenti recuperati direttamente dalla raccolta e non dipende dall'elaborazione di altre espressioni di raccolta.Such an expression represents a set of documents retrieved from the collection directly, and is not dependent on the processing of other collection expressions.

  • Un'espressione ha un ambito documento se l'origine dell'espressione di raccolta sottostante è input_alias introdotta in precedenza nella query.An expression is document-scoped, if the underlying source of the collection expression is input_alias introduced earlier in the query. Tale espressione rappresenta un set di documenti ottenuti dalla valutazione dell'espressione di raccolta nell'ambito di ogni documento appartenente al set associato alla raccolta con alias.Such an expression represents a set of documents obtained by evaluating the collection expression in the scope of each document belonging to the set associated with the aliased collection. Il set risultante sarà un'unione di set ottenuti dalla valutazione dell'espressione di raccolta per ogni documento del set sottostante.The resulting set will be a union of sets obtained by evaluating the collection expression for each of the documents in the underlying set.

JoinJoins

Nella versione corrente, Azure Cosmos DB supporta gli inner join.In the current release, Azure Cosmos DB supports inner joins. Altre funzionalità di join saranno presto disponibili.Additional join capabilities are forthcoming.

Gli inner join generano un prodotto incrociato completo dei set che partecipano al join.Inner joins result in a complete cross product of the sets participating in the join. Il risultato di un join a N vie è un set di tuple a N elementi, in cui ogni valore presente nella tupla è associato al set con alias che partecipa al join e l'accesso al set è possibile facendo riferimento a tale alias in altre clausole.The result of an N-way join is a set of N-element tuples, where each value in the tuple is associated with the aliased set participating in the join and can be accessed by referencing that alias in other clauses.

La valutazione del join dipende dall'ambito del contesto dei set partecipanti:The evaluation of the join depends on the context scope of the participating sets:

  • Un join tra il set di raccolta A e il set di raccolta con ambito B genera un prodotto incrociato di tutti gli elementi presenti nei set A e B.A join between collection-set A and collection-scoped set B, results in a cross product of all elements in sets A and B.

  • Un join tra il set A e il set con ambito documento B genera un'unione di tutti i set ottenuti dalla valutazione di un set con ambito documento B per ogni documento del set A.A join between set A and document-scoped set B, results in a union of all sets obtained by evaluating document-scoped set B for each document from set A.

    Nella versione corrente l'elaborazione delle query supporta al massimo un'espressione con ambito raccolta.In the current release, a maximum of one collection-scoped expression is supported by the query processor.

Esempi di join:Examples of joins:

Verrà ora esaminata la seguente clausola FROM: <from_source1> JOIN <from_source2> JOIN ... JOIN <from_sourceN>Let's look at the following FROM clause: <from_source1> JOIN <from_source2> JOIN ... JOIN <from_sourceN>

Consentire a ogni origine di definire input_alias1, input_alias2, …, input_aliasN.Let each source define input_alias1, input_alias2, …, input_aliasN. Questa clausola FROM restituisce un set di N tuple (tuple con N valori).This FROM clause returns a set of N-tuples (tuple with N values). Ogni tupla ha valori prodotti dall'iterazione di tutti gli alias della raccolta sui rispettivi set.Each tuple has values produced by iterating all collection aliases over their respective sets.

Esempio di JOIN 1, con 2 origini:JOIN example 1, with 2 sources:

  • Consentire a <from_source1> di avere un ambito raccolta e di rappresentare il set {A, B, C}.Let <from_source1> be collection-scoped and represent set {A, B, C}.

  • Consentire a <from_source2> di avere un ambito documento che fa riferimento a input_alias1 e di rappresentare i set:Let <from_source2> be document-scoped referencing input_alias1 and represent sets:

    {1, 2} per input_alias1 = A,{1, 2} for input_alias1 = A,

    {3} per input_alias1 = B,{3} for input_alias1 = B,

    {4, 5} per input_alias1 = C,{4, 5} for input_alias1 = C,

  • La clausola FROM <from_source1> JOIN <from_source2> produrrà le tuple seguenti:The FROM clause <from_source1> JOIN <from_source2> will result in the following tuples:

    (input_alias1, input_alias2):(input_alias1, input_alias2):

    (A, 1), (A, 2), (B, 3), (C, 4), (C, 5)

Esempio di JOIN 2, con 3 origini:JOIN example 2, with 3 sources:

  • Consentire a <from_source1> di avere un ambito raccolta e di rappresentare il set {A, B, C}.Let <from_source1> be collection-scoped and represent set {A, B, C}.

  • Consentire a <from_source2> di avere un ambito documento che fa riferimento input_alias1 e di rappresentare i set:Let <from_source2> be document-scoped referencing input_alias1 and represent sets:

    {1, 2} per input_alias1 = A,{1, 2} for input_alias1 = A,

    {3} per input_alias1 = B,{3} for input_alias1 = B,

    {4, 5} per input_alias1 = C,{4, 5} for input_alias1 = C,

  • Consentire a <from_source3> di avere un ambito documento che fa riferimento input_alias2 e di rappresentare i set:Let <from_source3> be document-scoped referencing input_alias2 and represent sets:

    {100, 200} per input_alias2 = 1,{100, 200} for input_alias2 = 1,

    {300} per input_alias2 = 3,{300} for input_alias2 = 3,

  • La clausola FROM <from_source1> JOIN <from_source2> JOIN <from_source3> produrrà le tuple seguenti:The FROM clause <from_source1> JOIN <from_source2> JOIN <from_source3> will result in the following tuples:

    (input_alias1, input_alias2, input_alias3):(input_alias1, input_alias2, input_alias3):

    (A, 1, 100), (A, 1, 200), (B, 3, 300)(A, 1, 100), (A, 1, 200), (B, 3, 300)

Nota

Mancano le tuple per altri valori di input_alias1, input_alias2, per cui <from_source3> non ha restituito alcun valore.Lack of tuples for other values of input_alias1, input_alias2, for which the <from_source3> did not return any values.

Esempio di JOIN 3, con 3 origini:JOIN example 3, with 3 sources:

  • Consentire a <from_source1> di avere un ambito raccolta e di rappresentare il set {A, B, C}.Let <from_source1> be collection-scoped and represent set {A, B, C}.

  • Consentire a <from_source1> di avere un ambito raccolta e di rappresentare il set {A, B, C}.Let <from_source1> be collection-scoped and represent set {A, B, C}.

  • Consentire a <from_source2> di avere un ambito documento che fa riferimento a input_alias1 e di rappresentare i set:Let <from_source2> be document-scoped referencing input_alias1 and represent sets:

    {1, 2} per input_alias1 = A,{1, 2} for input_alias1 = A,

    {3} per input_alias1 = B,{3} for input_alias1 = B,

    {4, 5} per input_alias1 = C,{4, 5} for input_alias1 = C,

  • Consentire a <from_source3> di avere ambito input_alias1 e rappresentare i set:Let <from_source3> be scoped to input_alias1 and represent sets:

    {100, 200} per input_alias2 = A,{100, 200} for input_alias2 = A,

    {300} per input_alias2 = C,{300} for input_alias2 = C,

  • La clausola FROM <from_source1> JOIN <from_source2> JOIN <from_source3> produrrà le tuple seguenti:The FROM clause <from_source1> JOIN <from_source2> JOIN <from_source3> will result in the following tuples:

    (input_alias1, input_alias2, input_alias3):(input_alias1, input_alias2, input_alias3):

    (A, 1, 100), (A, 1, 200), (A, 2, 100), (A, 2, 200), (C, 4, 300) , (C, 5, 300)(A, 1, 100), (A, 1, 200), (A, 2, 100), (A, 2, 200), (C, 4, 300) , (C, 5, 300)

Nota

Viene generato un prodotto incrociato tra <from_source2> e <from_source3> perché entrambi hanno come ambito lo stesso elemento <from_source1>.This resulted in cross product between <from_source2> and <from_source3> because both are scoped to the same <from_source1>. Sono state create 4 (2x2) tuple con valore A, 0 tuple con valore B (1 x 0) e 2 (2x1) tuple con valore C.This resulted in 4 (2x2) tuples having value A, 0 tuples having value B (1x0) and 2 (2x1) tuples having value C.

Vedere ancheSee also

Clausola SELECTSELECT clause

Clausola WHEREWHERE clause

Specifica la condizione di ricerca per i documenti restituiti dalla query.Specifies the search condition for the documents returned by the query.

SintassiSyntax

WHERE <filter_condition>  
<filter_condition> ::= <scalar_expression>  

ArgomentiArguments

  • <filter_condition>

    Specifica la condizione che deve essere soddisfatta per i documenti da restituire.Specifies the condition to be met for the documents to be returned.

  • <scalar_expression>

    Espressione che rappresenta il valore da calcolare.Expression representing the value to be computed. Vedere la sezione Espressioni scalari per informazioni dettagliate.See the Scalar expressions section for details.

    OsservazioniRemarks

    Affinché il documento venga restituito, un'espressione specificata come condizione di filtro deve restituire true.In order for the document to be returned an expression specified as filter condition must evaluate to true. Solo un valore booleano true soddisferà la condizione, i valori non definiti, null, false, numero, matrice o oggetto non soddisfano la condizione.Only Boolean value true will satisfy the condition, any other value: undefined, null, false, Number, Array or Object will not satisfy the condition.

Clausola ORDER BYORDER BY clause

Specifica l'ordinamento dei risultati restituiti dalla query.Specifies the sorting order for results returned by the query.

SintassiSyntax

ORDER BY <sort_specification>  
<sort_specification> ::= <sort_expression> [, <sort_expression>]  
<sort_expression> ::= <scalar_expression> [ASC | DESC]  

ArgomentiArguments

  • <sort_specification>

    Specifica una proprietà o espressione in cui ordinare il set di risultati della query.Specifies a property or expression on which to sort the query result set. Una colonna di ordinamento può essere specificata come alias di nome o di colonna.A sort column can be specified as a name or column alias.

    È possibile specificare più colonne di ordinamento.Multiple sort columns can be specified. I nomi delle colonne devono essere univoci.Column names must be unique. La sequenza delle colonne di ordinamento nella clausola ORDER BY definisce l'organizzazione del set di risultati ordinato.The sequence of the sort columns in the ORDER BY clause defines the organization of the sorted result set. Ovvero, il set di risultati viene ordinato in base alla prima proprietà e quindi l'elenco così ordinato viene ordinato in base alla seconda proprietà e così via.That is, the result set is sorted by the first property and then that ordered list is sorted by the second property, and so on.

    I nomi delle colonne a cui si fa riferimento nella clausola ORDER BY devono corrispondere a una colonna dell'elenco di selezione o a una colonna definita in una tabella specificata nella clausola FROM senza ambiguità.The column names referenced in the ORDER BY clause must correspond to either a column in the select list or to a column defined in a table specified in the FROM clause without any ambiguities.

  • <sort_expression>

    Specifica una singola proprietà o espressione in cui ordinare il set di risultati della query.Specifies a single property or expression on which to sort the query result set.

  • <scalar_expression>

    Vedere la sezione Espressioni scalari per informazioni dettagliate.See the Scalar expressions section for details.

  • ASC | DESC

    Specifica che i valori presenti nella colonna specificata devono essere ordinati in ordine crescente o decrescente.Specifies that the values in the specified column should be sorted in ascending or descending order. ASC (crescente) esegue l'ordinamento dal valore più basso a quello più alto.ASC sorts from the lowest value to highest value. DESC (decrescente) esegue l'ordinamento dal valore più alto a quello più basso.DESC sorts from highest value to lowest value. L'ordinamento predefinito è ASC (crescente).ASC is the default sort order. I valori Null vengono considerati come i valori più bassi possibile.Null values are treated as the lowest possible values.

    OsservazioniRemarks

    Benché la sintassi di query supporti più proprietà di ordinamento, il runtime di query di Azure Cosmos DB supporta l'ordinamento solo in base a una singola proprietà e solo in base ai nomi di proprietà, ovvero non in base a proprietà calcolate.While the query grammar supports multiple order by properties, the Azure Cosmos DB query runtime supports sorting only against a single property, and only against property names, i.e., not against computed properties. L'ordinamento richiede anche che i criteri di indicizzazione includano un indice di intervallo per la proprietà e il tipo specificato, con la massima precisione.Sorting also requires that the indexing policy includes a range index for the property and the specified type, with the maximum precision. Per informazioni dettagliate, fare riferimento alla documentazione sui criteri di indicizzazione.Refer to the indexing policy documentation for more details.

Espressioni scalariScalar expressions

Un'espressione scalare è una combinazione di simboli e operatori che si può valutare per ottenere un singolo valore.A scalar expression is a combination of symbols and operators that can be evaluated to obtain a single value. Le espressioni semplici possono essere costanti, riferimenti a proprietà, riferimenti a elementi di matrice, riferimenti ad alias o chiamate di funzioni.Simple expressions can be constants, property references, array element references, alias references, or function calls. Le espressioni semplici possono essere combinate in espressioni complesse usando gli operatori.Simple expressions can be combined into complex expressions using operators.

Per informazioni dettagliate sui valori che possono essere contenuti nelle espressioni scalari, vedere la sezione relativa alle costanti.For details on values which scalar expression may have, see Constants section.

SintassiSyntax

<scalar_expression> ::=  
       <constant>   
     | input_alias   
     | parameter_name  
     | <scalar_expression>.property_name  
     | <scalar_expression>'['"property_name"|array_index']'  
     | unary_operator <scalar_expression>  
     | <scalar_expression> binary_operator <scalar_expression>    
     | <scalar_expression> ? <scalar_expression> : <scalar_expression>  
     | <scalar_function_expression>  
     | <create_object_expression>   
     | <create_array_expression>  
     | (<scalar_expression>)   

<scalar_function_expression> ::=  
        'udf.' Udf_scalar_function([<scalar_expression>][,…n])  
        | builtin_scalar_function([<scalar_expression>][,…n])  

<create_object_expression> ::=  
   '{' [{property_name | "property_name"} : <scalar_expression>][,…n] '}'  

<create_array_expression> ::=  
   '[' [<scalar_expression>][,…n] ']'  

ArgomentiArguments

  • <constant>

    Rappresenta un valore costante.Represents a constant value. Per informazioni dettagliate, vedere la sezione Costanti.See Constants section for details.

  • input_alias

    Rappresenta un valore definito dall'elemento input_alias introdotto nella clausola FROM.Represents a value defined by the input_alias introduced in the FROM clause.
    Questo valore è sicuramente diverso da un valore non definito: i valori non definiti presenti nell'input verranno ignorati.This value is guaranteed to not be undefinedundefined values in the input are skipped.

  • <scalar_expression>.property_name

    Rappresenta un valore della proprietà di un oggetto.Represents a value of the property of an object. Se la proprietà non esiste o si fa riferimento alla proprietà per un valore che non è un oggetto, l'espressione restituisce un valore non definito.If the property does not exist or property is referenced on a value which is not an object, then the expression evaluates to undefined value.

  • <scalar_expression>'['"property_name"|array_index']'

    Rappresenta un valore della proprietà con nome property_name o un elemento di matrice con indice array_index di un oggetto o una matrice.Represents a value of the property with name property_name or array element with index array_index of an object/array. Se l'indice della proprietà o matrice non esiste o si fa riferimento all'indice della proprietà o matrice per un valore che non è un oggetto o una matrice, l'espressione restituisce un valore non definito.If the property/array index does not exist or the property/array index is referenced on a value which is not an object/array, then the expression evaluates to undefined value.

  • unary_operator <scalar_expression>

    Rappresenta un operatore applicato a un singolo valore.Represents an operator that is applied to a single value. Per informazioni dettagliate, vedere la sezione Operatori.See Operators section for details.

  • <scalar_expression> binary_operator <scalar_expression>

    Rappresenta un operatore applicato a due valori.Represents an operator that is applied to two values. Per informazioni dettagliate, vedere la sezione Operatori.See Operators section for details.

  • <scalar_function_expression>

    Rappresenta un valore definito da un risultato di una chiamata di funzione.Represents a value defined by a result of a function call.

  • udf_scalar_function

    Nome della funzione scalare definita dall'utente.Name of the user defined scalar function.

  • builtin_scalar_function

    Nome della funzione scalare predefinita.Name of the built-in scalar function.

  • <create_object_expression>

    Rappresenta un valore ottenuto creando un nuovo oggetto con proprietà specificate e i relativi valori.Represents a value obtained by creating a new object with specified properties and their values.

  • <create_array_expression>

    Rappresenta un valore ottenuto creando una nuova matrice con valori specificati come elementiRepresents a value obtained by creating a new array with specified values as elements

  • parameter_name

    Rappresenta un valore del nome di parametro specificato.Represents a value of the specified parameter name. I nomi di parametro devono avere un singolo carattere @ come primo carattere.Parameter names must have a single @ as the first character.

    OsservazioniRemarks

    Quando si chiama una funzione scalare predefinita o definita dall'utente è necessario definire tutti gli argomenti.When calling a built-in or user defined scalar function all arguments must be defined. Se uno degli argomenti non è definito, la funzione non verrà chiamata e il risultato sarà indefinito.If any of the arguments is undefined, the function will not be called and the result will be undefined.

    Quando si crea un oggetto, qualsiasi proprietà a cui viene assegnato un valore non definito verrà ignorata e non inclusa nell'oggetto creato.When creating an object, any property that is assigned undefined value will be skipped and not included in the created object.

    Quando si crea una matrice, qualsiasi valore di elemento a cui viene assegnato un valore non definito verrà ignorato e non incluso nell'oggetto creato.When creating an array, any element value that is assigned undefined value will be skipped and not included in the created object. Ciò causa la sostituzione dell'elemento da parte dell'elemento definito successivo in modo tale che la matrice creata non abbia indici ignorati.This will cause the next defined element to take its place in such a way that the created array will not have skipped indexes.

OperatoriOperators

Questa sezione descrive gli operatori supportati.This section describes the supported operators. Ogni operatore può essere assegnato a esattamente una categoria.Each operator can be assigned to exactly one category.

Vedere la tabella delle categorie di operatori riportata di seguito per informazioni dettagliate sulla gestione dei valori non definiti, sui requisiti di tipi per valori di input e sulla gestione dei valori con tipi non corrispondenti.See Operator categories table below, for details regarding handling of undefined values, type requirements for input values and handling of values with not matching types.

Categorie di operatori:Operator categories:

CategoriaCategory DettagliDetails
aritmeticoarithmetic L'operatore prevede che gli input siano numerici.Operator expects input(s) to be Number(s). Anche l'output è un numero.Output is also a Number. Se uno degli input è non definito o di tipo diverso da un numero, il risultato è non definito.If any of the inputs is undefined or type other than Number then the result is undefined.
bit per bitbitwise L'operatore prevede che gli input siano numeri interi con segno a 32 bit.Operator expects input(s) to be 32-bit signed integer Number(s). Anche l'output è un numero intero con segno a 32 bit.Output is also 32-bit signed integer Number.

Gli eventuali valori non interi vengono arrotondati.Any non-integer value will be rounded. I valori positivi verranno arrotondati per difetto, i valori negativi per eccesso.Positive value will be rounded down, negative values rounded up.

Qualsiasi valore esterno all'intervallo di interi a 32 bit verrà convertito prendendo gli ultimi 32 bit della relativa notazione di complemento a due.Any value that is outside of the 32-bit integer range will be converted, by taking last 32-bits of its two's complement notation.

Se uno degli input è non definito o di tipo diverso da un numero, il risultato è non definito.If any of the inputs is undefined or type other than Number, then the result is undefined.

Nota: il comportamento descritto sopra è compatibile con il comportamento di un operatore bit per bit di JavaScript.Note: The above behavior is compatible with JavaScript bitwise operator behavior.
logicological L'operatore prevede che gli input siano valori booleani.Operator expects input(s) to be Boolean(s). Anche l'output è un valore booleano.Output is also a Boolean.
Se uno degli input è non definito o di tipo diverso da un valore booleano, il risultato sarà non definito.If any of the inputs is undefined or type other than Boolean, then the result will be undefined.
confrontocomparison L'operatore prevede che gli input abbiano lo stesso tipo e non siano indefiniti.Operator expects input(s) to have the same type and not be undefined. L'output è un valore booleano.Output is a Boolean.

Se uno degli input è non definito o gli input hanno tipi diversi, il risultato è non definito.If any of the inputs is undefined or the inputs have different types, then the result is undefined.

Vedere la tabella dell'ordinamento dei valori per il confronto per informazioni dettagliate sull'ordinamento dei valori.See Ordering of values for comparison table for value ordering details.
stringstring L'operatore prevede che gli input siano stringhe.Operator expects input(s) to be String(s). Anche l'output è una stringa.Output is also a String.
Se uno degli input è non definito o di tipo diverso da una stringa, il risultato è non definito.If any of the inputs is undefined or type other than String then the result is undefined.

Operatori unari:Unary operators:

NomeName OperatoreOperator DettagliDetails
aritmeticoarithmetic +

-
Restituisce il valore numerico.Returns the number value.

Negazione bit per bit.Bitwise negation. Restituisce il valore numerico negato.Returns negated number value.
bit per bitbitwise ~ Complemento a uno.Ones' complement. Restituisce un complemento di un valore numerico.Returns a complement of a number value.
LogicoLogical NOTNOT Negazione.Negation. Restituisce un valore booleano negato.Returns negated Boolean value.

Operatori binari:Binary operators:

NomeName OperatoreOperator DettagliDetails
aritmeticoarithmetic +

-

*

/

%
Addizione.Addition.

Sottrazione.Subtraction.

Moltiplicazione.Multiplication.

Divisione.Division.

Modulazione.Modulation.
bit per bitbitwise ||

&

^

<<

>>

>>>
OR bit per bit.Bitwise OR.

AND bit per bit.Bitwise AND.

XOR bit per bit.Bitwise XOR.

Spostamento a sinistra.Left Shift.

Spostamento a destra.Right Shift.

Spostamento a destra riempimento zero.Zero-fill Right Shift.
logicological ANDAND

OROR
Congiunzione logica.Logical conjunction. Restituisce true se entrambi gli argomenti sono true, altrimenti restituisce false.Returns true if both arguments are true, returns false otherwise.

Congiunzione logica.Logical conjunction. Restituisce true se entrambi gli argomenti sono true, altrimenti restituisce false.Returns true if both arguments are true, returns false otherwise.
confrontocomparison =

!=, <>!=, <>

>

>=

<

<=

????
Uguale a.Equals. Restituisce true se gli argomenti sono uguali, altrimenti restituisce false.Returns true if arguments are equal, returns false otherwise.

Diverso da.Not equal to. Restituisce true se gli argomenti non sono uguali, altrimenti restituisce false.Returns true if arguments are not equal, returns false otherwise.

Maggiore di.Greater Than. Restituisce true se il primo argomento è maggiore del secondo, altrimenti restituisce false.Returns true if first argument is greater than the second one, return false otherwise.

Maggiore o uguale a.Greater Than or Equal To. Restituisce true se il primo argomento è maggiore o uguale al secondo, altrimenti restituisce false.Returns true if first argument is greater than or equal to the second one, return false otherwise.

Minore di.Less Than. Restituisce true se il primo argomento è minore del secondo, altrimenti restituisce false.Returns true if first argument is less than the second one, return false otherwise.

Minore o uguale a.Less Than or Equal To. Restituisce true se il primo argomento è minore o uguale al secondo, altrimenti restituisce false.Returns true if first argument is less than or equal to the second one, return false otherwise.

Unione.Coalesce. Restituisce il secondo argomento se il primo argomento è un valore non definito.Returns the second argument if the first argument is an undefined value.
StringaString |||| Concatenazione.Concatenation. Restituisce una concatenazione di entrambi gli argomenti.Returns a concatenation of both arguments.

Operatori ternari:Ternary operators:

Operatore ternarioTernary operator ?? Restituisce il secondo argomento se il primo argomento restituisce true, altrimenti restituisce il terzo argomento.Returns the second argument if the first argument evaluates to true; return the third argument otherwise.

Ordinamento dei valori per il confrontoOrdering of values for comparison

TipoType Ordine dei valoriValues order
UndefinedUndefined Non confrontabile.Not comparable.
NullNull Singolo valore: nullSingle value: null
NumberNumber Numero reale naturale.Natural real number.

Il valore infinito negativo è minore di qualsiasi altro valore numerico.Negative Infinity value is smaller than any other Number value.

Il valore infinito positivo è maggiore di qualsiasi altro valore numerico. il valore NaN non è confrontabile.Positive Infinity value is larger than any other Number value.NaN value is not comparable. Il confronto con NaN restituisce un valore non definito.Comparing with NaN will result in undefined value.
StringString Ordine lessicografico.Lexicographical order.
ArrayArray Nessun ordinamento, ma equo.No ordering, but equitable.
ObjectObject Nessun ordinamento, ma equo.No ordering, but equitable.

OsservazioniRemarks

In Azure Cosmos DB i tipi di valori sono spesso sconosciuti finché non vengono materialmente recuperati dal database.In Azure Cosmos DB, the types of values are often not known until they are actually retrieved from the database. Per supportare un'esecuzione efficiente delle query, gran parte degli operatori presentano rigorosi requisiti di tipi.In order to support efficient execution of queries, most of the operators have strict type requirements. Inoltre, gli operatori di per sé non eseguono conversioni implicite.Also operators by themselves do not perform implicit conversions.

Ciò significa che una query come: SELECT * FROM ROOT r WHERE r.Age = 21 restituisce solo documenti con la proprietà Age uguale al numero 21.This means that a query like: SELECT * FROM ROOT r WHERE r.Age = 21 will only return documents with property Age equal to the number 21. I documenti con la proprietà Age uguale alla stringa "21" o alla stringa "0021" non corrispondono, poiché l'espressione "21" = 21 restituisce un valore non definito.Documents with property Age equal to the string "21" or the string "0021" will not match, as the expression "21" = 21 evaluates to undefined. Questo consente un uso migliore degli indici, poiché la ricerca di un valore specifico, ovvero il numero 21, è più veloce rispetto alla ricerca di un numero indefinito di possibili corrispondenze (il numero 21 o le stringhe "21", "021", "21.0"...).This allows for a better use of indexes, because the lookup of a specific value (i.e. number 21) is faster than search for indefinite number of potential matches (i.e. number 21 or strings "21", "021", "21.0" …). Ciò si differenzia dal modo in cui JavaScript valuta gli operatori per valori di tipi diversi.This is different from how JavaScript evaluates operators on values of different types.

Confronto e uguaglianza di oggetti e matriciArrays and objects equality and comparison

Il confronto dei valori di oggetto o matrice con gli operatori di intervallo (>, >=, <, <=) produce un risultato indefinito poiché non è definito un ordine per i valori di oggetto o matrice.Comparing of Array or Object values using range operators (>, >=, <, <=) will result in undefined as there is not order defined on Object or Array values. Tuttavia l'uso degli operatori di uguaglianza/disuguaglianza (=,! =, <>) è supportato e i valori vengono confrontati strutturalmente.However using equality/inequality operators (=, !=, <>) is supported and values will be compared structurally.

Le matrici sono uguali se entrambe le matrici hanno stesso numero di elementi e sono uguali anche gli elementi nelle posizioni corrispondenti.Arrays are equal if both arrays have same number of elements and elements at matching positions are also equal. Se il confronto di qualsiasi coppia di elementi produce un risultato indefinito, il risultato del confronto di matrici è indefinito.If comparing any pair of elements results in undefined, the result of array comparison is undefined.

Gli oggetti sono uguali se entrambi gli oggetti hanno le stesse proprietà definite e se anche i valori delle proprietà corrispondenti sono uguali.Objects are equal if both objects have same properties defined, and if values of matching properties are also equal. Se il confronto di qualsiasi coppia di valori di proprietà produce un risultato indefinito, il risultato del confronto di oggetti è indefinito.If comparing any pair of property values results in undefined, the result of object comparison is undefined.

CostantiConstants

Una costante, nota anche come valore letterale o scalare, è un simbolo che rappresenta un valore di dati specifico.A constant, also known as a literal or a scalar value, is a symbol that represents a specific data value. Il formato di una costante dipende dal tipo di dati del valore che rappresenta.The format of a constant depends on the data type of the value it represents.

Tipi di dati scalari supportati:Supported scalar data types:

TipoType Ordine dei valoriValues order
UndefinedUndefined Singolo valore: non definitoSingle value: undefined
NullNull Singolo valore: nullSingle value: null
BooleanBoolean Valori: false, true.Values: false, true.
NumberNumber Un numero a virgola mobile e precisione doppia, standard IEEE 754.A double-precision floating-point number, IEEE 754 standard.
StringString Una sequenza di zero o più caratteri Unicode.A sequence of zero or more Unicode characters. Le stringhe devono essere racchiuse tra virgolette singole o doppie.Strings must be enclosed in single or double quotes.
ArrayArray Una sequenza di zero o più elementi.A sequence of zero or more elements. Ogni elemento può essere un valore di qualsiasi tipo di dati scalare, tranne Undefined.Each element can be a value of any scalar data type, except Undefined.
ObjectObject Un set non ordinato di zero o più coppie nome/valore.An unordered set of zero or more name/value pairs. Il nome è una stringa Unicode, il valore può essere di qualsiasi tipo di dati scalare, tranne Undefined.Name is a Unicode string, value can be of any scalar data type, except Undefined.

SintassiSyntax

<constant> ::=  
   <undefined_constant>  
     | <null_constant>   
     | <boolean_constant>   
     | <number_constant>   
     | <string_constant>   
     | <array_constant>   
     | <object_constant>   

<undefined_constant> ::= undefined  

<null_constant> ::= null  

<boolean_constant> ::= false | true  

<number_constant> ::= decimal_literal | hexadecimal_literal  

<string_constant> ::= string_literal  

<array_constant> ::=  
    '[' [<constant>][,...n] ']'  

<object_constant> ::=   
   '{' [{property_name | "property_name"} : <constant>][,...n] '}'  

ArgomentiArguments

  1. <undefined_constant>; undefined

    Rappresenta un valore non definito di tipo Undefined.Represents undefined value of type Undefined.

  2. <null_constant>; null

    Rappresenta un valore null di tipo Null.Represents null value of type Null.

  3. <boolean_constant>

    Rappresenta una costante di tipo Boolean.Represents constant of type Boolean.

  4. false

    Rappresenta un valore false di tipo booleano.Represents false value of type Boolean.

  5. true

    Rappresenta un valore true di tipo booleano.Represents true value of type Boolean.

  6. <number_constant>

    Rappresenta una costante.Represents a constant.

  7. decimal_literal

    I valori letterali decimali sono numeri rappresentati usando la notazione decimale o la notazione scientifica.Decimal literals are numbers represented using either decimal notation, or scientific notation.

  8. hexadecimal_literal

    I valori letterali esadecimali sono numeri rappresentati usando il prefisso "0x" seguito da una o più cifre esadecimali.Hexadecimal literals are numbers represented using prefix '0x' followed by one or more hexadecimal digits.

  9. <string_constant>

    Rappresenta una costante di tipo String.Represents a constant of type String.

  10. string _literal

    I valori letterali stringa sono stringhe Unicode rappresentate da una sequenza di zero o più caratteri Unicode o sequenze di escape.String literals are Unicode strings represented by a sequence of zero or more Unicode characters or escape sequences. I valori letterali stringa sono racchiusi tra virgolette singole (apostrofo: ') o virgolette doppie (virgolette inglesi: ").String literals are enclosed in single quotes (apostrophe: ' ) or double quotes (quotation mark: ").

    Sono consentite le sequenze di escape seguenti:Following escape sequences are allowed:

Sequenza di escapeEscape sequence DescrizioneDescription Carattere UnicodeUnicode character
\'\' apostrofo (')apostrophe (') U + 0027U+0027
\"\" virgolette doppie (")quotation mark (") U + 0022U+0022
\|barra rovesciata (\)reverse solidus (\) U + 005CU+005C
\/ barra (/)solidus (/) U + 002FU+002F
\b\b BACKSPACEbackspace U + 0008U+0008
\f\f avanzamento cartaform feed U + 000CU+000C
\n avanzamento rigaline feed U + 000AU+000A
\r\r ritorno a capocarriage return U + 000DU+000D
\t\t TABtab U + 0009U+0009
\uXXXX\uXXXX Carattere Unicode definito da 4 cifre esadecimali.A Unicode character defined by 4 hexadecimal digits. U + XXXXU+XXXX

Linee guida sulle prestazioni delle queryQuery performance guidelines

Per poter eseguire una query in modo efficiente per una raccolta di grandi dimensioni, è necessario usare filtri che possano essere gestiti attraverso uno o più indici.In order for a query to be executed efficiently for a large collection, it should use filters which can be served through one or more indexes.

Per la ricerca negli indici vengono considerati questi filtri:The following filters will be considered for index lookup:

  • Usare l'operatore di uguaglianza (=) con un'espressione percorso documenti e una costante.Use equality operator ( = ) with a document path expression and a constant.

  • Usare gli operatori di intervallo (<, <=, >, >=) con un'espressione percorso documenti e costanti numeriche.Use range operators (<, <=, >, >=) with a document path expression and number constants.

  • Con "espressione percorso documenti" si indica qualsiasi espressione che identifica un percorso costante nei documenti provenienti dalla raccolta di database a cui si fa riferimento.Document path expression stands for any expression which identifies a constant path in the documents from the referenced database collection.

    Espressione percorso documentiDocument path expression

    Le espressioni percorso documenti sono espressioni usate in un percorso di funzioni di valutazione dell'indicizzatore proprietà o matrice per un documento proveniente da documenti di una raccolta di database.Document path expressions are expressions that a path of property or array indexer assessors over a document coming from database collection documents. Questo percorso può essere usato per identificare la posizione dei valori a cui si fa riferimento in un filtro direttamente all'interno dei documenti della raccolta di database.This path can be used to identify the location of values referenced in a filter directly within the documents in the database collection.

    Per essere considerata un'espressione percorso documenti, è necessario che un'espressione:For an expression to be considered a document path expression, it should:

  1. Faccia riferimento direttamente alla radice della raccolta.Reference the collection root directly.

  2. Faccia riferimento all'indicizzatore di proprietà o matrici costanti di un'espressione percorso documentiReference property or constant array indexer of some document path expression

  3. Faccia riferimento a un alias che rappresenta un'espressione percorso documenti.Reference an alias, which represents some document path expression.

    Convenzioni della sintassiSyntax conventions

    Nella tabella seguente vengono descritte le convenzioni usate per descrivere la sintassi nel riferimento del linguaggio di query dell'API di DocumentDB.The following table describes the conventions used to describe syntax in the DocumentDB API Query Language reference.

    ConvenzioneConvention Usata perUsed for
    LETTERE MAIUSCOLEUPPERCASE Parole chiave che non fanno distinzione tra maiuscole e minuscole.Case-insensitive keywords.
    lettere minuscolelowercase Parole chiave che fanno distinzione tra maiuscole e minuscole.Case-sensitive keywords.
    <non terminale><nonterminal> Non terminale, definito separatamente.Nonterminal, defined separately.
    <non terminale> ::=<nonterminal> ::= Definizione di sintassi dell'elemento non terminale.Syntax definition of the nonterminal.
    altro_terminaleother_terminal Terminale (token), descritto dettagliatamente con parole.Terminal (token), described in detail in words.
    identificatoreidentifier Identificatore.Identifier. Consente solo i seguenti caratteri: a-z A-Z 0-9 _Il primo carattere non può essere una cifra.Allows following characters only: a-z A-Z 0-9 _First character cannot be a digit.
    "stringa""string" Stringa tra virgolette.Quoted string. Consente qualsiasi stringa valida.Allows any valid string. Vedere la descrizione di string_literal.See description of a string_literal.
    'simbolo''symbol' Simbolo letterale che fa parte della sintassi.Literal symbol which is part of the syntax.
    | (barra verticale)| (vertical bar) Alternative per gli elementi di sintassi.Alternatives for syntax items. È possibile usare solo uno degli elementi specificati.You can use only one of the items specified.
    [ ] /(parentesi quadre)[ ] /(brackets) Le parentesi quadre racchiudono uno o più elementi facoltativi.Brackets enclose one or more optional items.
    [ ,...n ][ ,...n ] Indica che l'elemento precedente può essere ripetuto n volte.Indicates the preceding item can be repeated n number of times. Le occorrenze sono separate da virgole.The occurrences are separated by commas.
    [ ...n ][ ...n ] Indica che l'elemento precedente può essere ripetuto n volte.Indicates the preceding item can be repeated n number of times. Le occorrenze sono separate da spazi.The occurrences are separated by blanks.

Funzioni predefiniteBuilt-in functions

In Azure Cosmos DB sono disponibili molte funzioni SQL predefinite.Azure Cosmos DB provides many built-in SQL functions. Le categorie di funzioni predefinite sono elencate di seguito.The categories of built-in functions are listed below.

FunzioneFunction DescrizioneDescription
Funzioni matematicheMathematical functions Le funzioni matematiche eseguono un calcolo basato in genere su valori di input passati come argomenti e restituiscono un valore numerico.The mathematical functions each perform a calculation, usually based on input values that are provided as arguments, and return a numeric value.
Funzioni di controllo del tipoType checking functions Le funzioni di controllo del tipo consentono di controllare il tipo di un'espressione nell'ambito delle query SQL.The type checking functions allow you to check the type of an expression within SQL queries.
Funzioni stringaString functions Le funzioni stringa eseguono un'operazione su un valore di stringa di input e restituiscono una stringa, il valore numerico o booleano.The string functions perform an operation on a string input value and return a string, numeric or Boolean value.
Funzioni di matriceArray functions Le funzioni di matrice eseguono un'operazione su un valore di input di matrice e restituiscono un valore numerico, booleano o matrice.The array functions perform an operation on an array input value and return numeric, Boolean or array value.
Funzioni spazialiSpatial functions Le funzioni spaziali eseguono un'operazione su un valore di input di oggetto spaziale e restituiscono un valore numerico o booleano.The spatial functions perform an operation on an spatial object input value and return a numeric or Boolean value.

Funzioni matematicheMathematical functions

Le seguenti funzioni eseguono un calcolo basato in genere su valori di input passati come argomenti e restituiscono un valore numerico.The following functions each perform a calculation, usually based on input values that are provided as arguments, and return a numeric value.

ABSABS ACOSACOS ASINASIN
ATANATAN ATN2ATN2 CEILINGCEILING
COSCOS COTCOT DEGREESDEGREES
EXPEXP FLOORFLOOR LOGLOG
LOG10LOG10 PIPI POWERPOWER
RADIANSRADIANS ROUNDROUND SINSIN
SQRTSQRT SQUARESQUARE SIGNSIGN
TANTAN TRUNCTRUNC

ABSABS

Restituisce il valore assoluto (positivo) dell'espressione numerica specificata.Returns the absolute (positive) value of the specified numeric expression.

SintassiSyntax

ABS (<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    Nell'esempio seguente vengono illustrati i risultati dell'uso della funzione ABS su tre numeri diversi.The following example shows the results of using the ABS function on three different numbers.

SELECT ABS(-1), ABS(0), ABS(1)  

Questo è il set di risultati.Here is the result set.

[{$1: 1, $2: 0, $3: 1}]  

ACOSACOS

Restituisce l'angolo, espresso in radianti, il cui coseno corrisponde all'espressione numerica specificata. Denominato anche arcocoseno.Returns the angle, in radians, whose cosine is the specified numeric expression; also called arccosine.

SintassiSyntax

ACOS(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce l'arcocoseno di -1.The following example returns the ACOS of -1.

SELECT ACOS(-1)  

Questo è il set di risultati.Here is the result set.

[{"$1": 3.1415926535897931}]  

ASINASIN

Restituisce l'angolo, espresso in radianti, il cui seno è l'espressione numerica specificata.Returns the angle, in radians, whose sine is the specified numeric expression. Detta anche arcoseno.This is also called arcsine.

SintassiSyntax

ASIN(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce l'arcoseno di -1.The following example returns the ASIN of -1.

SELECT ASIN(-1)  

Questo è il set di risultati.Here is the result set.

[{"$1": -1.5707963267948966}]  

ATANATAN

Restituisce l'angolo, espresso in radianti, la cui tangente è l'espressione numerica specificata.Returns the angle, in radians, whose tangent is the specified numeric expression. Detta anche arcotangente.This is also called arctangent.

SintassiSyntax

ATAN(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce l'arcotangente del valore specificato.The following example returns the ATAN of the specified value.

SELECT ATAN(-45.01)  

Questo è il set di risultati.Here is the result set.

[{"$1": -1.5485826962062663}]  

ATN2ATN2

Restituisce il valore principale dell'arcotangente di y/x, espresso in radianti.Returns the principal value of the arc tangent of y/x, expressed in radians.

SintassiSyntax

ATN2(<numeric_expression>, <numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente calcola l'arcotangente per i componenti x e y specificati.The following example calculates the ATN2 for the specified x and y components.

SELECT ATN2(35.175643, 129.44)  

Questo è il set di risultati.Here is the result set.

[{"$1": 1.3054517947300646}]  

CEILINGCEILING

Restituisce il più piccolo valore integer maggiore di o uguale all'espressione numerica specificata.Returns the smallest integer value greater than, or equal to, the specified numeric expression.

SintassiSyntax

CEILING (<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente usa valori numerici positivi, negativi e zero con la funzione CEILING.The following example shows positive numeric, negative, and zero values with the CEILING function.

SELECT CEILING(123.45), CEILING(-123.45), CEILING(0.0)  

Questo è il set di risultati.Here is the result set.

[{$1: 124, $2: -123, $3: 0}]  

COSCOS

Restituisce il coseno trigonometrico dell'angolo specificato, espresso in radianti, nell'espressione specificata.Returns the trigonometric cosine of the specified angle, in radians, in the specified expression.

SintassiSyntax

COS(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente calcola il coseno dell'angolo specificato.The following example calculates the COS of the specified angle.

SELECT COS(14.78)  

Questo è il set di risultati.Here is the result set.

[{"$1": -0.59946542619465426}]  

COTCOT

Restituisce la cotangente trigonometrica dell'angolo specificato, espresso in radianti, nell'espressione numerica specificata.Returns the trigonometric cotangent of the specified angle, in radians, in the specified numeric expression.

SintassiSyntax

COT(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente calcola la cotangente dell'angolo specificato.The following example calculates the COT of the specified angle.

SELECT COT(124.1332)  

Questo è il set di risultati.Here is the result set.

[{"$1": -0.040311998371148884}]  

DEGREESDEGREES

Restituisce l'angolo corrispondente in gradi di un angolo specificato in radianti.Returns the corresponding angle in degrees for an angle specified in radians.

SintassiSyntax

DEGREES (<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce il numero di gradi di un angolo di PI/2 radianti.The following example returns the number of degrees in an angle of PI/2 radians.

SELECT DEGREES(PI()/2)  

Questo è il set di risultati.Here is the result set.

[{"$1": 90}]  

FLOORFLOOR

Restituisce il valore integer più alto, minore di o uguale all'espressione numerica specificata.Returns the largest integer less than or equal to the specified numeric expression.

SintassiSyntax

FLOOR (<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente usa valori numerici positivi, negativi e zero con la funzione FLOOR.The following example shows positive numeric, negative, and zero values with the FLOOR function.

SELECT FLOOR(123.45), FLOOR(-123.45), FLOOR(0.0)  

Questo è il set di risultati.Here is the result set.

[{$1: 123, $2: -124, $3: 0}]  

EXPEXP

Restituisce il valore esponenziale dell'espressione numerica specificata.Returns the exponential value of the specified numeric expression.

SintassiSyntax

EXP (<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    OsservazioniRemarks

    La costante e (2,718281 …) è la base dei logaritmi naturali.The constant e (2.718281…), is the base of natural logarithms.

    L'esponente di un numero è la costante e elevata alla potenza del numero.The exponent of a number is the constant e raised to the power of the number. Ad esempio, EXP(1.0) = e^1.0 = 2,71828182845905 e EXP(10) = e^10 = 22026,4657948067.For example EXP(1.0) = e^1.0 = 2.71828182845905 and EXP(10) = e^10 = 22026.4657948067.

    Il valore esponenziale del logaritmo naturale di un numero è il numero stesso: EXP (LOG (n)) = n.The exponential of the natural logarithm of a number is the number itself: EXP (LOG (n)) = n. E il logaritmo naturale dell'esponente di un numero è il numero stesso: LOG (EXP (n)) = n.And the natural logarithm of the exponential of a number is the number itself: LOG (EXP (n)) = n.

    esempiExamples

    Nell'esempio seguente viene dichiarata una variabile e restituito il valore esponenziale della variabile specificata (10).The following example declares a variable and returns the exponential value of the specified variable (10).

SELECT EXP(10)  

Questo è il set di risultati.Here is the result set.

[{$1: 22026.465794806718}]  

L'esempio seguente restituisce il valore esponenziale del logaritmo naturale di 20 e il logaritmo naturale dell'esponente di 20.The following example returns the exponential value of the natural logarithm of 20 and the natural logarithm of the exponential of 20. Poiché queste funzioni sono inverse l'una dell'altra, il valore restituito con arrotondamento per il calcolo a virgola mobile in entrambi i casi è 20.Because these functions are inverse functions of one another, the return value with rounding for floating point math in both cases is 20.

SELECT EXP(LOG(20)), LOG(EXP(20))  

Questo è il set di risultati.Here is the result set.

[{$1: 19.999999999999996, $2: 20}]  

LOGLOG

Restituisce il logaritmo naturale dell'espressione numerica specificata.Returns the natural logarithm of the specified numeric expression.

SintassiSyntax

LOG (<numeric_expression> [, <base>])  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

  • base

    Argomento numerico facoltativo che imposta la base per il logaritmo.Optional numeric argument that sets the base for the logarithm.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    OsservazioniRemarks

    Per impostazione predefinita, LOG() restituisce il logaritmo naturale.By default, LOG() returns the natural logarithm. È possibile modificare la base del logaritmo e impostare un altro valore usando il parametro di base facoltativo.You can change the base of the logarithm to another value by using the optional base parameter.

    Il logaritmo naturale è il logaritmo in base e, dove e è una costante irrazionale approssimativamente uguale a 2,718281828.The natural logarithm is the logarithm to the base e, where e is an irrational constant approximately equal to 2.718281828.

    Il logaritmo naturale dell'esponente di un numero è il numero stesso: LOG ( EXP ( n ) ) = n.The natural logarithm of the exponential of a number is the number itself: LOG( EXP( n ) ) = n. E il valore esponenziale del logaritmo naturale di un numero è il numero stesso: EXP( LOG( n ) ) = n.And the exponential of the natural logarithm of a number is the number itself: EXP( LOG( n ) ) = n.

    esempiExamples

    Nell'esempio seguente viene dichiarata una variabile e restituito il logaritmo della variabile specificata (10).The following example declares a variable and returns the logarithm value of the specified variable (10).

SELECT LOG(10)  

Questo è il set di risultati.Here is the result set.

[{$1: 2.3025850929940459}]  

L'esempio seguente calcola il logaritmo per l'esponente di un numero.The following example calculates the LOG for the exponent of a number.

SELECT EXP(LOG(10))  

Questo è il set di risultati.Here is the result set.

[{$1: 10.000000000000002}]  

LOG10LOG10

Restituisce il logaritmo in base 10 dell'espressione numerica specificata.Returns the base-10 logarithm of the specified numeric expression.

SintassiSyntax

LOG10 (<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    OsservazioniRemarks

    Le funzioni LOG10 e POWER sono inversamente correlate tra loro.The LOG10 and POWER functions are inversely related to one another. Ad esempio, 10 ^ LOG10(n) = n.For example, 10 ^ LOG10(n) = n.

    esempiExamples

    Nell'esempio seguente viene dichiarata una variabile e restituito il valore LOG10 della variabile specificata (100).The following example declares a variable and returns the LOG10 value of the specified variable (100).

SELECT LOG10(100)  

Questo è il set di risultati.Here is the result set.

[{$1: 2}]  

PIPI

Restituisce il valore costante di pi greco.Returns the constant value of PI.

SintassiSyntax

PI ()  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce il valore di pi greco.The following example returns the value of PI.

SELECT PI()  

Questo è il set di risultati.Here is the result set.

[{"$1": 3.1415926535897931}]  

POWERPOWER

Restituisce il valore dell'espressione specificata alla potenza specificata.Returns the value of the specified expression to the specified power.

SintassiSyntax

POWER (<numeric_expression>, <y>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

  • y

    È la potenza a cui elevare numeric_expression.Is the power to which to raise numeric_expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    Nell'esempio seguente viene elevato un numero alla potenza di 3 (cubo del numero).The following example demonstrates raising a number to the power of 3 (the cube of the number).

SELECT POWER(2, 3), POWER(2.5, 3)  

Questo è il set di risultati.Here is the result set.

[{$1: 8, $2: 15.625}]  

RADIANSRADIANS

Restituisce radianti quando viene immessa un'espressione numerica, espresso in gradi.Returns radians when a numeric expression, in degrees, is entered.

SintassiSyntax

RADIANS (<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente accetta alcuni angoli come input e restituisce i valori in radianti corrispondenti.The following example takes a few angles as input and returns their corresponding radian values.

SELECT RADIANS(-45.01), RADIANS(-181.01), RADIANS(0), RADIANS(0.1472738), RADIANS(197.1099392)  

Questo è il set di risultati.Here is the result set.

[{  
       "$1": -0.7855726963226477,  
       "$2": -3.1592204790349356,  
       "$3": 0,  
       "$4": 0.0025704127119236249,  
       "$5": 3.4402174274458375  
   }]  

ROUNDROUND

Restituisce un valore numerico, arrotondato al valore integer più vicino.Returns a numeric value, rounded to the closest integer value.

SintassiSyntax

ROUND(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente arrotonda numeri positivi e negativi al numero intero più prossimo.The following example rounds the following positive and negative numbers to the nearest integer.

SELECT ROUND(2.4), ROUND(2.6), ROUND(2.5), ROUND(-2.4), ROUND(-2.6)  

Questo è il set di risultati.Here is the result set.

[{$1: 2, $2: 3, $3: 3, $4: -2, $5: -3}]  

SIGNSIGN

Restituisce il segno positivo (+1), zero (0) o negativo (-1) dell'espressione numerica specificata.Returns the positive (+1), zero (0), or negative (-1) sign of the specified numeric expression.

SintassiSyntax

SIGN(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce i valori SIGN dei numeri da -2 a 2.The following example returns the SIGN values of numbers from -2 to 2.

SELECT SIGN(-2), SIGN(-1), SIGN(0), SIGN(1), SIGN(2)  

Questo è il set di risultati.Here is the result set.

[{$1: -1, $2: -1, $3: 0, $4: 1, $5: 1}]  

SINSIN

Restituisce il seno trigonometrico dell'angolo specificato, espresso in radianti, nell'espressione specificata.Returns the trigonometric sine of the specified angle, in radians, in the specified expression.

SintassiSyntax

SIN(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente calcola il seno dell'angolo specificato.The following example calculates the SIN of the specified angle.

SELECT SIN(45.175643)  

Questo è il set di risultati.Here is the result set.

[{"$1": 0.929607286611012}]  

SQRTSQRT

Restituisce la radice quadrata del valore numerico specificato.Returns the square root of the specified numeric value.

SintassiSyntax

SQRT(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce le radici quadrate dei numeri da 1 a 3.The following example returns the square roots of numbers 1-3.

SELECT SQRT(1), SQRT(2.0), SQRT(3)  

Questo è il set di risultati.Here is the result set.

[{$1: 1, $2: 1.4142135623730952, $3: 1.7320508075688772}]  

SQUARESQUARE

Restituisce il quadrato del valore numerico specificato.Returns the square of the specified numeric value.

SintassiSyntax

SQUARE(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce i quadrati dei numeri da 1 a 3.The following example returns the squares of numbers 1-3.

SELECT SQUARE(1), SQUARE(2.0), SQUARE(3)  

Questo è il set di risultati.Here is the result set.

[{$1: 1, $2: 4, $3: 9}]  

TANTAN

Restituisce la tangente dell'angolo specificato, espresso in radianti, nell'espressione specificata.Returns the tangent of the specified angle, in radians, in the specified expression.

SintassiSyntax

TAN (<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente calcola la tangente di PI()/2.The following example calculates the tangent of PI()/2.

SELECT TAN(PI()/2);  

Questo è il set di risultati.Here is the result set.

[{"$1": 16331239353195370 }]  

TRUNCTRUNC

Restituisce un valore numerico, troncato al valore integer più vicino.Returns a numeric value, truncated to the closest integer value.

SintassiSyntax

TRUNC(<numeric_expression>)  

ArgomentiArguments

  • numeric_expression

    È un'espressione numerica.Is a numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente tronca numeri positivi e negativi al numero intero più prossimo.The following example truncates the following positive and negative numbers to the nearest integer value.

SELECT TRUNC(2.4), TRUNC(2.6), TRUNC(2.5), TRUNC(-2.4), TRUNC(-2.6)  

Questo è il set di risultati.Here is the result set.

[{$1: 2, $2: 2, $3: 2, $4: -2, $5: -2}]  

Funzioni di controllo del tipoType checking functions

Le funzioni seguenti supportano il controllo del tipo per i valori di input e ogni funzione restituisce un valore booleano.The following functions support type checking against input values, and each return a Boolean value.

IS_ARRAYIS_ARRAY IS_BOOLIS_BOOL IS_DEFINEDIS_DEFINED
IS_NULLIS_NULL IS_NUMBERIS_NUMBER IS_OBJECTIS_OBJECT
IS_PRIMITIVEIS_PRIMITIVE IS_STRINGIS_STRING

IS_ARRAYIS_ARRAY

Restituisce un valore booleano che indica se il tipo di espressione specificata è una matrice.Returns a Boolean value indicating if the type of the specified expression is an array.

SintassiSyntax

IS_ARRAY(<expression>)  

ArgomentiArguments

  • expression

    È qualsiasi espressione valida.Is any valid expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente controlla gli oggetti di tipo booleano JSON, numero, stringa, null, oggetto, matrice e non definito usando la funzione IS_ARRAY.The following example checks objects of JSON Boolean, number, string, null, object, array and undefined types using the IS_ARRAY function.

SELECT   
 IS_ARRAY(true),   
 IS_ARRAY(1),  
 IS_ARRAY("value"),  
 IS_ARRAY(null),  
 IS_ARRAY({prop: "value"}),   
 IS_ARRAY([1, 2, 3]),  
 IS_ARRAY({prop: "value"}.prop2)  

Questo è il set di risultati.Here is the result set.

[{$1: false, $2: false, $3: false, $4: false, $5: false, $6: true}]  

IS_BOOLIS_BOOL

Restituisce un valore booleano che indica se il tipo di espressione specificata è un valore booleano.Returns a Boolean value indicating if the type of the specified expression is a Boolean.

SintassiSyntax

IS_BOOL(<expression>)  

ArgomentiArguments

  • expression

    È qualsiasi espressione valida.Is any valid expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente controlla gli oggetti di tipo booleano JSON, numero, stringa, null, oggetto, matrice e non definito usando la funzione IS_BOOL.The following example checks objects of JSON Boolean, number, string, null, object, array and undefined types using the IS_BOOL function.

SELECT   
    IS_BOOL(true),   
    IS_BOOL(1),  
    IS_BOOL("value"),   
    IS_BOOL(null),  
    IS_BOOL({prop: "value"}),   
    IS_BOOL([1, 2, 3]),  
    IS_BOOL({prop: "value"}.prop2)  

Questo è il set di risultati.Here is the result set.

[{$1: true, $2: false, $3: false, $4: false, $5: false, $6: false}]  

IS_DEFINEDIS_DEFINED

Restituisce un valore booleano che indica se alla proprietà è stata assegnato un valore.Returns a Boolean indicating if the property has been assigned a value.

SintassiSyntax

IS_DEFINED(<expression>)  

ArgomentiArguments

  • expression

    È qualsiasi espressione valida.Is any valid expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente verifica la presenza di una proprietà all'interno del documento JSON specificato.The following example checks for the presence of a property within the specified JSON document. La prima parte restituisce true perché "a" è presente, ma la seconda restituisce false perché "b" è assente.The first returns true since "a" is present, but the second returns false since "b" is absent.

SELECT IS_DEFINED({ "a" : 5 }.a), IS_DEFINED({ "a" : 5 }.b)  

Questo è il set di risultati.Here is the result set.

[{  
       "$1": true,    
       "$2": false   
   }]  

IS_NULLIS_NULL

Restituisce un valore booleano che indica se il tipo di espressione specificata è nulla.Returns a Boolean value indicating if the type of the specified expression is null.

SintassiSyntax

IS_NULL(<expression>)  

ArgomentiArguments

  • expression

    È qualsiasi espressione valida.Is any valid expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente controlla gli oggetti di tipo booleano JSON, numero, stringa, null, oggetto, matrice e non definito usando la funzione IS_NULL.The following example checks objects of JSON Boolean, number, string, null, object, array and undefined types using the IS_NULL function.

SELECT   
    IS_NULL(true),   
    IS_NULL(1),  
    IS_NULL("value"),   
    IS_NULL(null),  
    IS_NULL({prop: "value"}),   
    IS_NULL([1, 2, 3]),  
    IS_NULL({prop: "value"}.prop2)  

Questo è il set di risultati.Here is the result set.

[{$1: false, $2: false, $3: false, $4: true, $5: false, $6: false}]  

IS_NUMBERIS_NUMBER

Restituisce un valore booleano che indica se il tipo di espressione specificata è un numero.Returns a Boolean value indicating if the type of the specified expression is a number.

SintassiSyntax

IS_NUMBER(<expression>)  

ArgomentiArguments

  • expression

    È qualsiasi espressione valida.Is any valid expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente controlla gli oggetti di tipo booleano JSON, numero, stringa, null, oggetto, matrice e non definito usando la funzione IS_NULL.The following example checks objects of JSON Boolean, number, string, null, object, array and undefined types using the IS_NULL function.

SELECT   
    IS_NUMBER(true),   
    IS_NUMBER(1),  
    IS_NUMBER("value"),   
    IS_NUMBER(null),  
    IS_NUMBER({prop: "value"}),   
    IS_NUMBER([1, 2, 3]),  
    IS_NUMBER({prop: "value"}.prop2)  

Questo è il set di risultati.Here is the result set.

[{$1: false, $2: true, $3: false, $4: false, $5: false, $6: false}]  

IS_OBJECTIS_OBJECT

Restituisce un valore booleano che indica se il tipo di espressione specificata è un oggetto JSON.Returns a Boolean value indicating if the type of the specified expression is a JSON object.

SintassiSyntax

IS_OBJECT(<expression>)  

ArgomentiArguments

  • expression

    È qualsiasi espressione valida.Is any valid expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente controlla gli oggetti di tipo booleano JSON, numero, stringa, null, oggetto, matrice e non definito usando la funzione IS_OBJECT.The following example checks objects of JSON Boolean, number, string, null, object, array and undefined types using the IS_OBJECT function.

SELECT   
    IS_OBJECT(true),   
    IS_OBJECT(1),  
    IS_OBJECT("value"),   
    IS_OBJECT(null),  
    IS_OBJECT({prop: "value"}),   
    IS_OBJECT([1, 2, 3]),  
    IS_OBJECT({prop: "value"}.prop2)  

Questo è il set di risultati.Here is the result set.

[{$1: false, $2: false, $3: false, $4: false, $5: true, $6: false}]  

IS_PRIMITIVEIS_PRIMITIVE

Restituisce un valore booleano che indica se il tipo di espressione specificata è un primitivo (stringa, valore booleano, numerico o null).Returns a Boolean value indicating if the type of the specified expression is a primitive (string, Boolean, numeric or null).

SintassiSyntax

IS_PRIMITIVE(<expression>)  

ArgomentiArguments

  • expression

    È qualsiasi espressione valida.Is any valid expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente controlla gli oggetti di tipo booleano JSON, numero, stringa, null, oggetto, matrice e non definito usando la funzione IS_PRIMITIVE.The following example checks objects of JSON Boolean, number, string, null, object, array and undefined types using the IS_PRIMITIVE function.

SELECT   
           IS_PRIMITIVE(true),   
           IS_PRIMITIVE(1),  
           IS_PRIMITIVE("value"),   
           IS_PRIMITIVE(null),  
           IS_PRIMITIVE({prop: "value"}),   
           IS_PRIMITIVE([1, 2, 3]),  
           IS_PRIMITIVE({prop: "value"}.prop2)  

Questo è il set di risultati.Here is the result set.

[{"$1": true, "$2": true, "$3": true, "$4": true, "$5": false, "$6": false, "$7": false}]  

IS_STRINGIS_STRING

Restituisce un valore booleano che indica se il tipo di espressione specificata è una stringa.Returns a Boolean value indicating if the type of the specified expression is a string.

SintassiSyntax

IS_STRING(<expression>)  

ArgomentiArguments

  • expression

    È qualsiasi espressione valida.Is any valid expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente controlla gli oggetti di tipo booleano JSON, numero, stringa, null, oggetto, matrice e non definito usando la funzione IS_STRING.The following example checks objects of JSON Boolean, number, string, null, object, array and undefined types using the IS_STRING function.

SELECT   
       IS_STRING(true),   
       IS_STRING(1),  
       IS_STRING("value"),   
       IS_STRING(null),  
       IS_STRING({prop: "value"}),   
       IS_STRING([1, 2, 3]),  
       IS_STRING({prop: "value"}.prop2)  

Questo è il set di risultati.Here is the result set.

[{$1: false, $2: false, $3: true, $4: false, $5: false, $6: false}]  

Funzioni stringaString functions

Le funzioni scalari seguenti eseguono un'operazione su un valore di stringa di input e restituiscono una stringa, il valore numerico o booleano.The following scalar functions perform an operation on a string input value and return a string, numeric or Boolean value.

CONCATCONCAT CONTAINSCONTAINS ENDSWITHENDSWITH
INDEX_OFINDEX_OF LEFTLEFT LENGTHLENGTH
LOWERLOWER LTRIMLTRIM REPLACEREPLACE
REPLICATEREPLICATE REVERSEREVERSE RIGHTRIGHT
RTRIMRTRIM STARTSWITHSTARTSWITH SUBSTRINGSUBSTRING
UPPERUPPER

CONCATCONCAT

Restituisce una stringa che rappresenta il risultato della concatenazione di due o più valori di stringa.Returns a string that is the result of concatenating two or more string values.

SintassiSyntax

CONCAT(<str_expr>, <str_expr> [, <str_expr>])  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente restituisce la stringa concatenata dei valori specificati.The following example returns the concatenated string of the specified values.

SELECT CONCAT("abc", "def")  

Questo è il set di risultati.Here is the result set.

[{"$1": "abcdef"}  

CONTAINSCONTAINS

Restituisce un valore booleano che indica se la prima espressione stringa contiene il secondo.Returns a Boolean indicating whether the first string expression contains the second.

SintassiSyntax

CONTAINS(<str_expr>, <str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    Nell'esempio seguente viene verificato se "abc" contiene "ab" e contiene "d".The following example checks if "abc" contains "ab" and contains "d".

SELECT CONTAINS("abc", "ab"), CONTAINS("abc", "d")  

Questo è il set di risultati.Here is the result set.

[{"$1": true, "$2": false}]  

ENDSWITHENDSWITH

Restituisce un valore booleano che indica se la prima espressione stringa termina con il secondo.Returns a Boolean indicating whether the first string expression ends with the second.

SintassiSyntax

ENDSWITH(<str_expr>, <str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente restituisce "abc" che termina con "b" e "bc".The following example returns the "abc" ends with "b" and "bc".

SELECT ENDSWITH("abc", "b"), ENDSWITH("abc", "bc")  

Questo è il set di risultati.Here is the result set.

[{"$1": false, "$2": true}]  

INDEX_OFINDEX_OF

Restituisce la posizione iniziale della prima occorrenza della seconda stringa di espressione all'interno della prima espressione stringa specificata oppure -1 se la stringa non viene trovata.Returns the starting position of the first occurrence of the second string expression within the first specified string expression, or -1 if the string is not found.

SintassiSyntax

INDEX_OF(<str_expr>, <str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente restituisce l'indice di diverse sottostringhe all'interno di "abc".The following example returns the index of various substrings inside "abc".

SELECT INDEX_OF("abc", "ab"), INDEX_OF("abc", "b"), INDEX_OF("abc", "c")  

Questo è il set di risultati.Here is the result set.

[{"$1": 0, "$2": 1, "$3": -1}]  

LEFTLEFT

Restituisce la parte sinistra di una stringa con il numero specificato di caratteri.Returns the left part of a string with the specified number of characters.

SintassiSyntax

LEFT(<str_expr>, <num_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

  • num_expr

    È qualsiasi espressione numerica valida.Is any valid numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente restituisce la parte sinistra di "abc" per diversi valori di lunghezza.The following example returns the left part of "abc" for various length values.

SELECT LEFT("abc", 1), LEFT("abc", 2)  

Questo è il set di risultati.Here is the result set.

[{"$1": "a", "$2": "ab"}]  

LENGTHLENGTH

Restituisce il numero di caratteri dell'espressione stringa specificata.Returns the number of characters of the specified string expression.

SintassiSyntax

LENGTH(<str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente restituisce la lunghezza di una stringa.The following example returns the length of a string.

SELECT LENGTH("abc")  

Questo è il set di risultati.Here is the result set.

[{"$1": 3}]  

LOWERLOWER

Restituisce un'espressione stringa dopo la conversione di dati in caratteri maiuscoli in caratteri minuscoli.Returns a string expression after converting uppercase character data to lowercase.

SintassiSyntax

LOWER(<str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente illustra come usare LOWER in una query.The following example shows how to use LOWER in a query.

SELECT LOWER("Abc")  

Questo è il set di risultati.Here is the result set.

[{"$1": "abc"}]  

LTRIMLTRIM

Restituisce un'espressione stringa dopo aver rimosso gli spazi vuoti iniziali.Returns a string expression after it removes leading blanks.

SintassiSyntax

LTRIM(<str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente illustra come usare LTRIM all'interno di una query.The following example shows how to use LTRIM inside a query.

SELECT LTRIM("  abc"), LTRIM("abc"), LTRIM("abc   ")  

Questo è il set di risultati.Here is the result set.

[{"$1": "abc", "$2": "abc", "$3": "abc   "}]  

REPLACEREPLACE

Sostituisce tutte le occorrenze di un valore stringa specificato con un altro valore stringa.Replaces all occurrences of a specified string value with another string value.

SintassiSyntax

REPLACE(<str_expr>, <str_expr>, <str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente illustra come usare REPLACE in una query.The following example shows how to use REPLACE in a query.

SELECT REPLACE("This is a Test", "Test", "desk")  

Questo è il set di risultati.Here is the result set.

[{"$1": "This is a desk"}]  

REPLICATEREPLICATE

Ripete un valore stringa in un numero di volte specificato.Repeats a string value a specified number of times.

SintassiSyntax

REPLICATE(<str_expr>, <num_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

  • num_expr

    È qualsiasi espressione numerica valida.Is any valid numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente illustra come usare REPLICATE in una query.The following example shows how to use REPLICATE in a query.

SELECT REPLICATE("a", 3)  

Questo è il set di risultati.Here is the result set.

[{"$1": "aaa"}]  

REVERSEREVERSE

Restituisce l'inverso di un valore stringa.Returns the reverse order of a string value.

SintassiSyntax

REVERSE(<str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente illustra come usare REVERSE in una query.The following example shows how to use REVERSE in a query.

SELECT REVERSE("Abc")  

Questo è il set di risultati.Here is the result set.

[{"$1": "cbA"}]  

RIGHTRIGHT

Restituisce la parte destra di una stringa con il numero specificato di caratteri.Returns the right part of a string with the specified number of characters.

SintassiSyntax

RIGHT(<str_expr>, <num_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

  • num_expr

    È qualsiasi espressione numerica valida.Is any valid numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente restituisce la parte destra di "abc" per diversi valori di lunghezza.The following example returns the right part of "abc" for various length values.

SELECT RIGHT("abc", 1), RIGHT("abc", 2)  

Questo è il set di risultati.Here is the result set.

[{"$1": "c", "$2": "bc"}]  

RTRIMRTRIM

Restituisce un'espressione di stringa dopo aver rimosso gli spazi vuoti finali.Returns a string expression after it removes trailing blanks.

SintassiSyntax

RTRIM(<str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente illustra come usare RTRIM all'interno di una query.The following example shows how to use RTRIM inside a query.

SELECT RTRIM("  abc"), RTRIM("abc"), RTRIM("abc   ")  

Questo è il set di risultati.Here is the result set.

[{"$1": "   abc", "$2": "abc", "$3": "abc"}]  

STARTSWITHSTARTSWITH

Restituisce un valore booleano che indica se la prima espressione stringa inizia con il secondo.Returns a Boolean indicating whether the first string expression starts with the second.

SintassiSyntax

STARTSWITH(<str_expr>, <str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    L'esempio seguente verifica se la stringa "abc" inizia con "b" e "a".The following example checks if the string "abc" begins with "b" and "a".

SELECT STARTSWITH("abc", "b"), STARTSWITH("abc", "a")  

Questo è il set di risultati.Here is the result set.

[{"$1": false, "$2": true}]  

SUBSTRINGSUBSTRING

Restituisce parte di un'espressione stringa a partire dalla posizione in base al carattere zero specificata e continua fino alla lunghezza specificata o alla fine della stringa.Returns part of a string expression starting at the specified character zero-based position and continues to the specified length, or to the end of the string.

SintassiSyntax

SUBSTRING(<str_expr>, <num_expr> [, <num_expr>])  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

  • num_expr

    È qualsiasi espressione numerica valida.Is any valid numeric expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente restituisce la sottostringa di "abc" a partire da 1 e per una lunghezza di 1 carattere.The following example returns the substring of "abc" starting at 1 and for a length of 1 character.

SELECT SUBSTRING("abc", 1, 1)  

Questo è il set di risultati.Here is the result set.

[{"$1": "b"}]  

UPPERUPPER

Restituisce un'espressione stringa dopo aver convertito i caratteri minuscoli in caratteri maiuscoli.Returns a string expression after converting lowercase character data to uppercase.

SintassiSyntax

UPPER(<str_expr>)  

ArgomentiArguments

  • str_expr

    È qualsiasi espressione di stringa valida.Is any valid string expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di stringa.Returns a string expression.

    esempiExamples

    L'esempio seguente illustra come usare UPPER in una queryThe following example shows how to use UPPER in a query

SELECT UPPER("Abc")  

Questo è il set di risultati.Here is the result set.

[{"$1": "ABC"}]  

Funzioni di matriceArray functions

Le funzioni scalari seguenti eseguono un'operazione su un valore di input di matrice e restituiscono un valore numerico, booleano o matriceThe following scalar functions perform an operation on an array input value and return numeric, Boolean or array value

ARRAY_CONCATARRAY_CONCAT ARRAY_CONTAINSARRAY_CONTAINS ARRAY_LENGTHARRAY_LENGTH
ARRAY_SLICEARRAY_SLICE

ARRAY_CONCATARRAY_CONCAT

Restituisce una matrice che rappresenta il risultato della concatenazione di due o più valori della matrice.Returns an array that is the result of concatenating two or more array values.

SintassiSyntax

ARRAY_CONCAT (<arr_expr>, <arr_expr> [, <arr_expr>])  

ArgomentiArguments

  • arr_expr

    È qualsiasi espressione di matrice valida.Is any valid array expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione di matrice.Returns an array expression.

    esempiExamples

    L'esempio seguente illustra come concatenare due matrici.The following example how to concatenate two arrays.

SELECT ARRAY_CONCAT(["apples", "strawberries"], ["bananas"])  

Questo è il set di risultati.Here is the result set.

[{"$1": ["apples", "strawberries", "bananas"]}]  

ARRAY_CONTAINSARRAY_CONTAINS

Restituisce un valore booleano che indica se la matrice contiene il valore specificato.Returns a Boolean indicating whether the array contains the specified value. Può specificare se la corrispondenza è completa o parziale.Can specify if the match is full or partial.

SintassiSyntax

ARRAY_CONTAINS (<arr_expr>, <expr> [, bool_expr])  

ArgomentiArguments

  • arr_expr

    È qualsiasi espressione di matrice valida.Is any valid array expression.

  • expr

    È qualsiasi espressione valida.Is any valid expression.

  • bool_expr

    È un'espressione booleana.Is any boolean expression.

    Tipi restituitiReturn Types

    Restituisce un valore booleano.Returns a Boolean value.

    esempiExamples

    L'esempio seguente illustra come verificare l'appartenenza a una matrice usando ARRAY_CONTAINS.The following example how to check for membership in an array using ARRAY_CONTAINS.

SELECT   
           ARRAY_CONTAINS(["apples", "strawberries", "bananas"], "apples"),  
           ARRAY_CONTAINS(["apples", "strawberries", "bananas"], "mangoes")  

Questo è il set di risultati.Here is the result set.

[{"$1": true, "$2": false}]  

L'esempio seguente illustra come verificare la corrispondenza di un JSON in una matrice usando ARRAY_CONTAINS.The following example how to check for a partial match of a JSON in an array using ARRAY_CONTAINS.

SELECT  
    ARRAY_CONTAINS([{"name": "apples", "fresh": true}, {"name": "strawberries", "fresh": true}], {"name": "apples"}, true), 
    ARRAY_CONTAINS([{"name": "apples", "fresh": true}, {"name": "strawberries", "fresh": true}], {"name": "apples"}),
    ARRAY_CONTAINS([{"name": "apples", "fresh": true}, {"name": "strawberries", "fresh": true}], {"name": "mangoes"}, true) 

Questo è il set di risultati.Here is the result set.

[{
  "$1": true,
  "$2": false,
  "$3": false
}] 

ARRAY_LENGTHARRAY_LENGTH

Restituisce il numero di elementi dell'espressione di matrice specificato.Returns the number of elements of the specified array expression.

SintassiSyntax

ARRAY_LENGTH(<arr_expr>)  

ArgomentiArguments

  • arr_expr

    È qualsiasi espressione di matrice valida.Is any valid array expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica.Returns a numeric expression.

    esempiExamples

    L'esempio seguente illustra come ottenere la lunghezza di una matrice usando ARRAY_LENGTH.The following example how to get the length of an array using ARRAY_LENGTH.

SELECT ARRAY_LENGTH(["apples", "strawberries", "bananas"])  

Questo è il set di risultati.Here is the result set.

[{"$1": 3}]  

ARRAY_SLICEARRAY_SLICE

Restituisce parte di un'espressione di matrice.Returns part of an array expression.

SintassiSyntax

ARRAY_SLICE (<arr_expr>, <num_expr> [, <num_expr>])  

ArgomentiArguments

  • arr_expr

    È qualsiasi espressione di matrice valida.Is any valid array expression.

  • num_expr

    È qualsiasi espressione numerica valida.Is any valid numeric expression.

    Tipi restituitiReturn Types

    Restituisce un valore booleano.Returns a Boolean value.

    esempiExamples

    L'esempio seguente illustra come ottenere una parte di una matrice usando ARRAY_SLICE.The following example how to get a part of an array using ARRAY_SLICE.

SELECT   
           ARRAY_SLICE(["apples", "strawberries", "bananas"], 1),  
           ARRAY_SLICE(["apples", "strawberries", "bananas"], 1, 1)  

Questo è il set di risultati.Here is the result set.

[{  
           "$1": ["strawberries", "bananas"],   
           "$2": ["strawberries"]  
       }]  

Funzioni spazialiSpatial functions

Le seguenti funzioni scalari eseguono un'operazione su un valore di input di oggetto spaziale e restituiscono un valore numerico o booleano.The following scalar functions perform an operation on an spatial object input value and return a numeric or Boolean value.

ST_DISTANCEST_DISTANCE ST_WITHINST_WITHIN ST_INTERSECTSST_INTERSECTS
ST_ISVALIDDETAILEDST_ISVALIDDETAILED

ST_DISTANCEST_DISTANCE

Restituisce la distanza tra le due espressioni GeoJSON punto, poligono o LineString.Returns the distance between the two GeoJSON Point, Polygon, or LineString expressions.

SintassiSyntax

ST_DISTANCE (<spatial_expr>, <spatial_expr>)  

ArgomentiArguments

  • spatial_expr

    È qualsiasi espressione di oggetto punto GeoJSON, poligono o LineString valida.Is any valid GeoJSON Point, Polygon, or LineString object expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione numerica che contiene la distanza.Returns a numeric expression containing the distance. È espressa in metri per il sistema di riferimento predefinito.This is expressed in meters for the default reference system.

    esempiExamples

    L'esempio seguente indica come restituire tutti i documenti della famiglia che si trovano entro 30 km dalla posizione specificata usando la funzione predefinita ST_DISTANCE.The following example shows how to return all family documents that are within 30 km of the specified location using the ST_DISTANCE built-in function. ..

SELECT f.id   
FROM Families f   
WHERE ST_DISTANCE(f.location, {'type': 'Point', 'coordinates':[31.9, -4.8]}) < 30000  

Questo è il set di risultati.Here is the result set.

[{  
  "id": "WakefieldFamily"  
}]  

ST_WITHINST_WITHIN

Restituisce un'espressione booleana che indica se l'oggetto GeoJSON (punto, poligono o LineString) specificato nel primo argomento è all'interno dell'oggetto GeoJSON (punto, poligono o LineString) nel secondo argomento.Returns a Boolean expression indicating whether the GeoJSON object (Point, Polygon, or LineString) specified in the first argument is within the GeoJSON (Point, Polygon, or LineString) in the second argument.

SintassiSyntax

ST_WITHIN (<spatial_expr>, <spatial_expr>)  

ArgomentiArguments

  • spatial_expr

    È qualsiasi espressione di oggetto punto GeoJSON, poligono o LineString valida.Is any valid GeoJSON Point, Polygon, or LineString object expression.

  • spatial_expr

    È qualsiasi espressione di oggetto punto GeoJSON, poligono o LineString valida.Is any valid GeoJSON Point, Polygon, or LineString object expression.

    Tipi restituitiReturn Types

    Restituisce un valore booleano.Returns a Boolean value.

    esempiExamples

    L'esempio seguente indica come trovare tutti i documenti della famiglia all'interno di un poligono usando ST_WITHIN.The following example shows how to find all family documents within a polygon using ST_WITHIN.

SELECT f.id   
FROM Families f   
WHERE ST_WITHIN(f.location, {  
    'type':'Polygon',   
    'coordinates': [[[31.8, -5], [32, -5], [32, -4.7], [31.8, -4.7], [31.8, -5]]]  
})  

Questo è il set di risultati.Here is the result set.

[{ "id": "WakefieldFamily" }]  

ST_INTERSECTSST_INTERSECTS

Restituisce un'espressione booleana che indica se l'oggetto GeoJSON (punto, poligono o LineString) specificato nel primo argomento interseca l'oggetto GeoJSON (punto, poligono o LineString) nel secondo argomento.Returns a Boolean expression indicating whether the GeoJSON object (Point, Polygon, or LineString) specified in the first argument intersects the GeoJSON (Point, Polygon, or LineString) in the second argument.

SintassiSyntax

ST_INTERSECTS (<spatial_expr>, <spatial_expr>)  

ArgomentiArguments

  • spatial_expr

    È qualsiasi espressione di oggetto punto GeoJSON, poligono o LineString valida.Is any valid GeoJSON Point, Polygon, or LineString object expression.

  • spatial_expr

    È qualsiasi espressione di oggetto punto GeoJSON, poligono o LineString valida.Is any valid GeoJSON Point, Polygon, or LineString object expression.

    Tipi restituitiReturn Types

    Restituisce un valore booleano.Returns a Boolean value.

    esempiExamples

    L'esempio seguente indica come individuare tutte le aree che intersecano il poligono dato.The following example shows how to find all areas that intersects with the given polygon.

SELECT a.id   
FROM Areas a   
WHERE ST_INTERSECTS(a.location, {  
    'type':'Polygon',   
    'coordinates': [[[31.8, -5], [32, -5], [32, -4.7], [31.8, -4.7], [31.8, -5]]]  
})  

Questo è il set di risultati.Here is the result set.

[{ "id": "IntersectingPolygon" }]  

ST_ISVALIDST_ISVALID

Restituisce un valore booleano che indica se l'espressione GeoJSON punto, poligono o LineString specificata è valida.Returns a Boolean value indicating whether the specified GeoJSON Point, Polygon, or LineString expression is valid.

SintassiSyntax

ST_ISVALID(<spatial_expr>)  

ArgomentiArguments

  • spatial_expr

    È qualsiasi espressione di punto GeoJSON, poligono o LineString valida.Is any valid GeoJSON Point, Polygon, or LineString expression.

    Tipi restituitiReturn Types

    Restituisce un'espressione booleana.Returns a Boolean expression.

    esempiExamples

    Nell'esempio seguente viene illustrato come controllare se un punto è valido usando ST_VALID.The following example shows how to check if a point is valid using ST_VALID.

    Ad esempio, questo punto ha un valore di latitudine che non rientra nell'intervallo valido di valori [-90, 90], quindi la query restituisce false.For example, this point has a latitude value that's not in the valid range of values [-90, 90], so the query returns false.

    Per i poligoni, la specifica GeoJSON richiede che l'ultima coppia di coordinate indicata corrisponda alla prima, in modo da creare una forma chiusa.For polygons, the GeoJSON specification requires that the last coordinate pair provided should be the same as the first, to create a closed shape. I punti all'interno di un poligono devono essere specificati in senso antiorario.Points within a polygon must be specified in counter-clockwise order. Un poligono specificato in senso orario rappresenta l'inverso dell'area al suo interno.A polygon specified in clockwise order represents the inverse of the region within it.

SELECT ST_ISVALID({ "type": "Point", "coordinates": [31.9, -132.8] })  

Questo è il set di risultati.Here is the result set.

[{ "$1": false }]  

ST_ISVALIDDETAILEDST_ISVALIDDETAILED

Restituisce un valore JSON che contiene un valore booleano valore se l'espressione GeoJSON punto, poligono o LineString specificata è valida e, se non valida, anche il motivo come valore stringa.Returns a JSON value containing a Boolean value if the specified GeoJSON Point, Polygon, or LineString expression is valid, and if invalid, additionally the reason as a string value.

SintassiSyntax

ST_ISVALID(<spatial_expr>)  

ArgomentiArguments

  • spatial_expr

    È qualsiasi espressione di punto GeoJSON o poligono valida.Is any valid GeoJSON point or polygon expression.

    Tipi restituitiReturn Types

    Restituisce un valore JSON che contiene un valore booleano valore se l'espressione punto o poligono GeoJSON specificata è valida e, se non valida, anche il motivo come valore stringa.Returns a JSON value containing a Boolean value if the specified GeoJSON point or polygon expression is valid, and if invalid, additionally the reason as a string value.

    esempiExamples

    Nell'esempio seguente viene illustrato come controllare la validità (con i dettagli) usando ST_ISVALIDDETAILED.The following example how to check validity (with details) using ST_ISVALIDDETAILED.

SELECT ST_ISVALIDDETAILED({   
  "type": "Polygon",   
  "coordinates": [[ [ 31.8, -5 ], [ 31.8, -4.7 ], [ 32, -4.7 ], [ 32, -5 ] ]]  
})  

Questo è il set di risultati.Here is the result set.

[{  
  "$1": {   
    "valid": false,   
    "reason": "The Polygon input is not valid because the start and end points of the ring number 1 are not the same. Each ring of a polygon must have the same start and end points."   
  }  
}]  

Passaggi successiviNext steps

Query e sintassi SQL per Azure Cosmos DB SQL syntax and SQL query for Azure Cosmos DB
Documentazione di Azure Cosmos DBAzure Cosmos DB documentation