Condividi tramite

CREA FUNZIONE

Si applica a:Endpoint di analisi SQL e Warehouse in Microsoft Fabric

CREATE FUNCTION può creare funzioni con valori di tabella inline e funzioni scalari.

Nota

Le funzioni definite dall'utente scalari sono una funzionalità di anteprima in Fabric Data Warehouse.

Importante

In Fabric Data Warehouse le funzioni definite dall'utente scalari devono essere inline per l'uso con SELECT ... FROM le query sulle tabelle utente, ma è comunque possibile creare funzioni non inline. Funzioni definite dall'utente scalari che non sono utilizzabili inline in un numero limitato di scenari. È possibile verificare se una funzione definita dall'utente può essere inlined.

Una funzione definita dall'utente è una routine Transact-SQL che accetta parametri, esegue un'azione, ad esempio un calcolo complesso, e restituisce il risultato di tale azione sotto forma di valore. Le funzioni scalari restituiscono un valore scalare, ad esempio un numero o una stringa. Le funzioni con valori di tabella definite dall'utente restituiscono una tabella.

Usare CREATE FUNCTION per creare una routine T-SQL riutilizzabile che può essere usata in questi modi:

  • Nelle istruzioni Transact-SQL, ad esempio SELECT
  • In Transact-SQL istruzioni di manipolazione dei dati (DML), ad esempio UPDATE, INSERTe DELETE
  • Nelle applicazioni che chiamano la funzione.
  • Nella definizione di un'altra funzione definita dall'utente.
  • Per sostituire una stored procedure.

Suggerimento

È possibile specificare CREATE OR ALTER FUNCTION di creare una nuova funzione se non esiste con tale nome o modificare una funzione esistente in una singola istruzione.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

Sintassi della funzione scalare

CREATE FUNCTION [ schema_name. ] function_name   
( [ { @parameter_name [ AS ] parameter_data_type   
    [ = default ] }   
    [ ,...n ]  
  ]  
)  
RETURNS return_data_type  
    [ WITH <function_option> [ ,...n ] ]  
    [ AS ]  
    BEGIN   
        function_body   
        RETURN scalar_expression  
    END  
[ ; ]  

<function_option>::=   
{  
    [ SCHEMABINDING ]  
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]  
}

Sintassi della funzione inline con valori di tabella

CREATE FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] parameter_data_type
    [ = default ] }
    [ ,...n ]
  ]
)
RETURNS TABLE
    [ WITH SCHEMABINDING ]
    [ AS ]
    RETURN [ ( ] select_stmt [ ) ]
[ ; ]

Argomenti

schema_name

Nome dello schema a cui appartiene la funzione definita dall'utente.

function_name

Nome della funzione definita dall'utente. I nomi di funzione devono essere conformi alle regole per gli identificatori e devono essere univoci all'interno del database e rispetto al relativo schema.

Nota

È necessario apporre le parentesi dopo il nome della funzione anche se non viene specificato alcun parametro.

@ parameter_name

Parametro nella funzione definita dall'utente. È possibile dichiarare uno o più parametri.

Una funzione può avere al massimo 2.100 parametri. Il valore di ciascun parametro dichiarato deve essere specificato dall'utente quando viene eseguita la funzione, a meno che non venga definito un valore predefinito per tale parametro.

Specificare un nome di parametro usando come primo carattere il simbolo di chiocciola (@). I nomi di parametro devono essere conformi alle regole per gli identificatori. I parametri sono locali rispetto alla funzione. È pertanto possibile utilizzare gli stessi nomi di parametro in altre funzioni. I parametri possono rappresentare solo costanti, non nomi di tabella, di colonna o di altri oggetti di database.

Nota

ANSI_WARNINGS non viene rispettato quando si passano parametri in una stored procedure, una funzione definita dall'utente o quando si dichiarano e si impostano variabili in un'istruzione batch. Se, ad esempio, la variabile viene definita come char(3) e quindi impostata su un valore maggiore di tre caratteri, i dati verranno troncati alla dimensione definita e l'istruzione INSERT o UPDATE avrà esito positivo.

parameter_data_type

Tipo di dati del parametro. Per le funzioni Transact-SQL sono consentiti tutti i tipi di dati scalari supportati .

[ = predefinito ]

Valore predefinito per il parametro. Se viene definito un valore default, è possibile eseguire la funzione senza specificare un valore per il parametro corrispondente a tale valore.

Quando un parametro della funzione ha un valore predefinito, la parola DEFAULT chiave deve essere specificata quando la funzione viene chiamata per recuperare il valore predefinito. Questo comportamento risulta diverso dall'utilizzo di parametri con valore predefinito nelle stored procedure in cui l'omissione del parametro implica l'utilizzo del valore predefinito.

return_data_type

Valore restituito di una funzione scalare definita dall'utente.

Per le funzioni in Fabric Data Warehouse, tutti i tipi di dati sono consentiti ad eccezione deltimestamprowversion/. Tipi non scalabili come la tabella non sono consentiti.

function_body

Serie di istruzioni Transact-SQL.

Nelle funzioni scalari function_body è una serie di istruzioni Transact-SQL che insieme restituiscono un valore scalare, che può includere:

  • Espressione di istruzione singola
  • Espressioni con più istruzioni (IF/THEN/ELSE e BEGIN/END blocchi)
  • Variabili locali
  • Chiamate alle funzioni SQL predefinite disponibili
  • Chiamate ad altre funzioni definite dall'utente
  • SELECT istruzioni e riferimenti a tabelle, viste e funzioni inline con valori di tabella

scalar_expression

Specifica il valore scalare restituito dalla funzione scalare.

select_stmt

Istruzione singola SELECT che definisce il valore restituito di una funzione con valori di tabella inline. Per una funzione inline con valori di tabella, non esiste alcun corpo della funzione; la tabella è il set di risultati di una singola SELECT istruzione.

TABELLA

Specifica che il valore restituito della funzione con valori di tabella è una tabella. Alle funzioni con valori di tabella è possibile passare solo costanti e @local_variables.

Nelle funzioni CONF inline (anteprima), il valore restituito TABLE viene definito tramite una singola SELECT istruzione. Alle funzioni inline non sono associate variabili restituite.

<function_option>

In Fabric Data Warehouse le INLINEparole chiave , ENCRYPTIONe EXECUTE AS non sono supportate.

Le opzioni di funzione supportate includono:

SCHEMABINDING

Specifica che la funzione è associata agli oggetti di database a cui fa riferimento. Quando la clausola SCHEMABINDING viene specificata, non è possibile apportare agli oggetti di base modifiche che hanno effetto sulla definizione della funzione. È necessario prima modificare o eliminare la definizione della funzione per rimuovere le dipendenze dall'oggetto da modificare.

L'associazione della funzione agli oggetti cui fa riferimento viene rimossa solo quando viene eseguita una delle azioni seguenti:

  • La funzione viene eliminata.

  • La funzione viene modificata tramite l'istruzione ALTER senza specificare l'opzione SCHEMABINDING.

Una funzione può essere associata a uno schema solo se vengono soddisfatte le condizioni seguenti:

  • Le funzioni definite dall'utente a cui la funzione fa riferimento sono anch'esse associate a uno schema.

  • Agli oggetti a cui fa riferimento la funzione viene fatto riferimento utilizzando un nome in due parti.

  • Alle funzioni predefinite e alle altre funzioni definite dall'utente nello stesso database è possibile fare riferimento solo all'interno del corpo di funzioni definite dall'utente.

  • L'utente che ha eseguito l'istruzione dispone dell'autorizzazione CREATE FUNCTION REFERENCES per gli oggetti di database a cui fa riferimento la funzione.

Per rimuovere SCHEMABINDING, usare ALTER.

RESTITUISCE NULL IN INPUT NULL | CHIAMATA SU INPUT NULL

Specifica l'attributo OnNULLCall di una funzione con valori scalari. Se non specificato, CALLED ON NULL INPUT è implicito per impostazione predefinita e il corpo della funzione viene eseguito anche se NULL viene passato come argomento.

Procedure consigliate

  • Se una funzione definita dall'utente non viene creata con schemabinding, le modifiche apportate agli oggetti sottostanti possono influire sulla definizione della funzione e produrre risultati imprevisti quando viene richiamato. È consigliabile specificare la WITH SCHEMABINDING clausola durante la creazione della funzione. In questo modo, gli oggetti a cui si fa riferimento nella definizione della funzione possono essere modificati solo se viene modificata anche la funzione.

  • Scrittura delle funzioni definite dall'utente in modo che siano inline. Per altre informazioni, vedere Inlining di funzioni definite dall'utente scalari.

Interoperabilità

Funzioni definite dall'utente con valori di tabella inline

In una funzione inline con valori di tabella è consentita solo una singola istruzione select.

Funzioni scalari definite dall'utente

  • In una funzione a valori scalari sono valide le istruzioni seguenti:

    • Istruzioni di assegnazione
    • Istruzioni Control-of-Flow ad eccezione TRY...CATCH delle istruzioni
    • DECLARE istruzioni che definiscono le variabili di dati locali

  • Le funzioni predefinite seguenti non sono supportate in un corpo di funzione scalare:

  • Le funzioni definite dall'utente scalari non possono essere usate in una SELECT ... FROM query su una tabella utente quando:

  • Le funzioni definite dall'utente scalari non possono essere usate in una query quando:

    • La funzione definita dall'utente viene chiamata direttamente in una GROUP BY clausola .
    • La funzione definita dall'utente viene chiamata direttamente in una ORDER BY clausola .
    • la chiamata di una query ha un'espressione di tabella comune (CTE).

  • Le funzioni definite dall'utente scalari ricorsive non sono supportate.

  • Una query utente può non riuscire se vengono effettuate più di 10 chiamate definite dall'utente in una singola query.

  • In alcuni casi limite, la complessità della query utente e del corpo della funzione definita dall'utente impedisce l'inlining, nel qual caso la funzione definita dall'utente scalare non è inlined e la query dell'utente non riesce.

  • Quando una funzione definita dall'utente scalare viene usata in qualsiasi scenario non supportato, viene visualizzato un messaggio di errore "Scalar UDF execution is currently unavailable in this context."

Limiti

Nota

Durante l'anteprima corrente, le limitazioni sono soggette a modifiche.

Non è possibile utilizzare funzioni definite dall'utente per eseguire azioni che modificano lo stato del database.

È possibile nidificare le funzioni definite dall'utente, ovvero una funzione definita dall'utente ne può richiamare un'altra. Il livello di nidificazione aumenta all'avvio della funzione richiamata e diminuisce al termine dell'esecuzione della funzione. Le funzioni definite dall'utente in Fabric Data Warehouse possono essere annidate fino a quattro livelli quando un corpo della funzione definita dall'utente fa riferimento a una funzione tabella/vista/tabella in linea o fino a 32 livelli in caso contrario. Il superamento dei livelli massimi di annidamento causa l'esito negativo della catena di funzioni chiamanti.

Metadati UFX

Nella sezione seguente vengono elencate le viste del catalogo di sistema usate per restituire i metadati sulle funzioni definite dall'utente.

  • sys.sql_modules: visualizza la definizione di Transact-SQL funzioni definite dall'utente. Ad esempio:

    SELECT definition, type   
FROM sys.sql_modules AS m  
JOIN sys.objects AS o   
    ON m.object_id = o.object_id   
    AND type = ('FN');

  • sys.parameters: visualizza informazioni sui parametri definiti nelle funzioni definite dall'utente.

  • sys.sql_expression_dependencies: visualizza gli oggetti sottostanti a cui fa riferimento una funzione.

Autorizzazioni

I membri dei ruoli Amministratore, Membro e Collaboratore dell'area di lavoro infrastruttura possono creare funzioni.

Inlining di funzioni definite dall'utente scalari

Microsoft Fabric Data Warehouse usa l'inlining di funzioni definite dall'utente scalari per compilare ed eseguire codice definito dall'utente in modo distribuito. L'inlining di funzioni definite dall'utente scalari è abilitato per impostazione predefinita.

Sebbene l'inlining di funzioni definite dall'utente scalari sia una tecnica di ottimizzazione delle prestazioni introdotta in Microsoft SQL Server 2019 (15.0), in Fabric Data Warehouse determina il set di scenari supportato. In Fabric Data Warehouse le funzioni definite dall'utente scalari vengono trasformate automaticamente in espressioni scalari o sottoquery scalari sostituite nella query chiamante al posto dell'operatore UDF.

Alcune sintassi T-SQL rendono nonlineabile una funzione definita dall'utente scalare. Le funzioni che contengono un WHILE ciclo, più RETURN istruzioni o una chiamata a una funzione predefinita SQL non deterministica (ad esempio GETUTCDATE() o GETDATE()) non possono essere inlinedi. Per altre informazioni, vedere Requisiti di inlining di funzioni definite dall'utente scalari.

Controllare se una funzione definita dall'utente scalare può essere inlined

La sys.sql_modules vista del catalogo include la colonna is_inlineable, che indica se una funzione definita dall'utente è inline.

La is_inlineable proprietà deriva dal controllo della sintassi all'interno della definizione della funzione definita dall'utente. La funzione definita dall'utente scalare non è inlined prima della fase di compilazione. Un valore indica 1 che la funzione definita dall'utente è inline, mentre un valore indica 0 che non è inline. Se una funzione definita dall'utente scalare è inline, non garantisce che venga sempre inlinedata quando la query viene compilata.

Fabric Data Warehouse decide (per query) se inline una funzione definita dall'utente, a seconda della complessità complessiva delle query.

Usare la query di esempio seguente per verificare se una funzione definita dall'utente scalare è inline:

SELECT 
SCHEMA_NAME(b.schema_id) as function_schema_name,
    b.name as function_name,
       b.type_desc as function_type,
       a.is_inlineable
FROM sys.sql_modules AS a
     INNER JOIN sys.objects AS b
         ON a.object_id = b.object_id
WHERE b.type IN ('FN');

Se una funzione scalare non è inline in sys.sql_modules.is_inlineable, è comunque possibile eseguire la query come chiamata autonoma, ad esempio, per impostare una variabile. Tuttavia, la funzione scalare non può far parte di una SELECT ... FROM query in una tabella utente. Ad esempio:

CREATE FUNCTION [dbo].[custom_SYSUTCDATETIME]()
  RETURNS datetime2(6)
  AS
  BEGIN
   RETURN SYSUTCDATETIME();
  END

La funzione scalare di esempio dbo.custom_SYSUTCDATETIME definita dall'utente non è inline a causa dell'uso di una funzione di sistema nonterminant, SYSUTCDATETIME(). L'operazione avrà esito negativo quando viene usata in una query in una SELECT ... FROM tabella utente, ma avrà esito positivo come chiamata autonoma, ad esempio:

DECLARE @utcdate datetime2(7);
SET @utcdate = dbo.custom_SYSUTCDATETIME();
SELECT @utcdate as 'utc_date';

Esempi

R. Creare una funzione inline con valori di tabella

L'esempio seguente crea una funzione inline con valori di tabella per restituire alcune informazioni chiave nei moduli, applicando un filtro in base al parametro objectType. Include un valore predefinito per restituire tutti i moduli quando la funzione viene chiamata con il DEFAULT parametro . Questo esempio usa alcune delle viste del catalogo di sistema indicate in Metadati.

CREATE FUNCTION dbo.ModulesByType (@objectType CHAR(2) = '%%')
RETURNS TABLE
AS
RETURN (
        SELECT sm.object_id AS 'Object Id',
            o.create_date AS 'Date Created',
            OBJECT_NAME(sm.object_id) AS 'Name',
            o.type AS 'Type',
            o.type_desc AS 'Type Description',
            sm.DEFINITION AS 'Module Description',
            sm.is_inlineable AS 'Inlineable'
        FROM sys.sql_modules AS sm
        INNER JOIN sys.objects AS o ON sm.object_id = o.object_id
        WHERE o.type LIKE '%' + @objectType + '%'
        );
GO

La funzione può quindi essere chiamata per restituire tutte le funzioni con valori di tabella inline (IF) con:

SELECT * FROM dbo.ModulesByType('IF'); -- SQL_INLINE_TABLE_VALUED_FUNCTION

In alternativa, trovare tutte le funzioni scalari (FN):

SELECT * FROM dbo.ModulesByType('FN'); -- SQL_SCALAR_FUNCTION

B. Combinare i risultati di una funzione inline con valori di tabella

Questo semplice esempio usa la funzione inline con valori di tabella creata in precedenza per dimostrare in che modo è possibile combinare i risultati con altre tabelle usando Cross Apply. In questo caso vengono selezionate tutte le colonne da e sys.objects i risultati di ModulesByType per tutte le righe corrispondenti nella type colonna. Per altre informazioni sull'uso di apply, vedere clausola FROM più JOIN, APPLY, PIVOT (Transact-SQL).

SELECT * 
FROM sys.objects AS o
CROSS APPLY dbo.ModulesByType(o.type);
GO

C. Creare una funzione UDF scalare

Nell'esempio seguente viene creata una funzione definita dall'utente scalare inline che maschera un testo di input.

CREATE OR ALTER FUNCTION [dbo].[cleanInput] (@InputString VARCHAR(100))
    RETURNS VARCHAR(50)
    AS
    BEGIN
        DECLARE @Result VARCHAR(50)
        DECLARE @CleanedInput VARCHAR(50)

        -- Trim whitespace
        SET @CleanedInput = LTRIM(RTRIM(@InputString))

        -- Handle empty or null input
        IF @CleanedInput = '' OR @CleanedInput IS NULL
        BEGIN
            SET @Result = ''
        END
        ELSE IF LEN(@CleanedInput) <= 2
        BEGIN
            -- If string length is 1 or 2, just return the cleaned string
            SET @Result = @CleanedInput
        END
        ELSE
        BEGIN
            -- Construct the masked string
            SET @Result = 
                LEFT(@CleanedInput, 1) +
                REPLICATE('*', LEN(@CleanedInput) - 2) +
                RIGHT(@CleanedInput, 1)
        END

        RETURN @Result
    END

È possibile chiamare la funzione come segue:

DECLARE @input varchar(100) = '123456789'

SELECT dbo.cleanInput (@input) AS function_output;

Altri esempi di come usare funzioni definite dall'utente scalari in Fabric Data Warehouse:

In un'istruzione SELECT :

SELECT TOP 10 
t.id, t.name, 
dbo.cleanInput (t.name) AS function_output
FROM dbo.MyTable AS t;

In una WHERE clausola:

 SELECT t.id, t.name, dbo.cleanInput(t.name) AS function_output
FROM dbo.MyTable AS t
WHERE dbo.cleanInput(t.name)='myvalue'

In una JOIN clausola:

SELECT t1.id, t1.name, 
     dbo.cleanInput (t1.name) AS function_output, 
     dbo.cleanInput (t2.name) AS function_output_2
FROM dbo.MyTable1 AS t1
    INNER JOIN dbo.MyTable2 AS t2 
        ON dbo.cleanInput(t1.name)=dbo.cleanInput(t2.name);

In una ORDER BY clausola:

SELECT  t.id, t.name, dbo.cleanInput (t.name) AS function_output
FROM dbo.MyTable AS t
ORDER BY function_output;

Nelle istruzioni DML (Data Manipulation Language) come INSERT, UPDATEo DELETE:

SELECT t.id, t.name, dbo.cleanInput (t.name) AS function_output 
INTO dbo.MyTable_new
FROM dbo.MyTable AS t;

UPDATE t
SET t.mycolumn_new = dbo.cleanInput (t.name)
FROM dbo.MyTable AS t;

DELETE t
FROM dbo.MyTable AS t
WHERE dbo.cleanInput (t.name) ='myvalue';

Contenuti correlati

Si applica a:Azure Synapse AnalyticsPiattaforma di strumenti analitici (PDW)

Crea una funzione definita dall'utente (UDF) in Azure Synapse Analytics o in Analytics Platform System (PDW). Una funzione definita dall'utente è una routine Transact-SQL che accetta parametri, esegue un'azione, ad esempio un calcolo complesso, e restituisce il risultato di tale azione sotto forma di valore. Le funzioni con valori di tabella definite dall'utente restituiscono un tipo di dati table.

  • Nella piattaforma di strumenti analitici (PDW) il valore restituito deve essere un valore scalare (singolo).

  • In Azure Synapse Analytics CREATE FUNCTION può restituire una tabella usando la sintassi per le funzioni con valori di tabella inline (anteprima) oppure può restituire un singolo valore usando la sintassi per le funzioni scalari.

  • Nei pool SQL serverless in Azure Synapse Analytics è CREATE FUNCTION possibile creare funzioni con valori di tabella inline ma non funzioni scalari.

    Utilizzare questa istruzione per creare una routine riutilizzabile che può essere utilizzata in queste modalità:

  • Nelle istruzioni Transact-SQL, ad esempio SELECT

  • Nelle applicazioni che chiamano la funzione.

  • Nella definizione di un'altra funzione definita dall'utente.

  • Per definire un vincolo CHECK su una colonna.

  • Per sostituire una stored procedure.

  • Usare una funzione inline come predicato di filtro per un criterio di sicurezza

Suggerimento

Per la sintassi in Fabric Data Warehouse, vedere la versione di CREATE FUNCTION per Microsoft Fabric Data Warehouse.

Convenzioni relative alla sintassi Transact-SQL

Sintassi

Sintassi della funzione scalare

-- Transact-SQL Scalar Function Syntax (in dedicated pools in Azure Synapse Analytics and Parallel Data Warehouse)
-- Not available in the serverless SQL pools in Azure Synapse Analytics

CREATE FUNCTION [ schema_name. ] function_name   
( [ { @parameter_name [ AS ] parameter_data_type   
    [ = default ] }   
    [ ,...n ]  
  ]  
)  
RETURNS return_data_type  
    [ WITH <function_option> [ ,...n ] ]  
    [ AS ]  
    BEGIN   
        function_body   
        RETURN scalar_expression  
    END  
[ ; ]  

<function_option>::=   
{  
    [ SCHEMABINDING ]  
  | [ RETURNS NULL ON NULL INPUT | CALLED ON NULL INPUT ]  
}

Sintassi della funzione inline con valori di tabella

-- Transact-SQL Inline Table-Valued Function Syntax
-- Preview in dedicated SQL pools in Azure Synapse Analytics
-- Available in the serverless SQL pools in Azure Synapse Analytics
CREATE FUNCTION [ schema_name. ] function_name
( [ { @parameter_name [ AS ] parameter_data_type
    [ = default ] }
    [ ,...n ]
  ]
)
RETURNS TABLE
    [ WITH SCHEMABINDING ]
    [ AS ]
    RETURN [ ( ] select_stmt [ ) ]
[ ; ]

Argomenti

schema_name

Nome dello schema a cui appartiene la funzione definita dall'utente.

function_name

Nome della funzione definita dall'utente. I nomi di funzione devono essere conformi alle regole per gli identificatori e devono essere univoci all'interno del database e rispetto al relativo schema.

Nota

È necessario apporre le parentesi dopo il nome della funzione anche se non viene specificato alcun parametro.

@ parameter_name

Parametro nella funzione definita dall'utente. È possibile dichiarare uno o più parametri.

Una funzione può avere al massimo 2.100 parametri. Il valore di ciascun parametro dichiarato deve essere specificato dall'utente quando viene eseguita la funzione, a meno che non venga definito un valore predefinito per tale parametro.

Specificare un nome di parametro usando come primo carattere il simbolo di chiocciola (@). I nomi di parametro devono essere conformi alle regole per gli identificatori. I parametri sono locali rispetto alla funzione. È pertanto possibile utilizzare gli stessi nomi di parametro in altre funzioni. I parametri possono rappresentare solo costanti, non nomi di tabella, di colonna o di altri oggetti di database.

Nota

ANSI_WARNINGS non viene rispettato quando si passano parametri in una stored procedure, una funzione definita dall'utente o quando si dichiarano e si impostano variabili in un'istruzione batch. Se, ad esempio, la variabile viene definita come char(3) e quindi impostata su un valore maggiore di tre caratteri, i dati verranno troncati alla dimensione definita e l'istruzione INSERT o UPDATE avrà esito positivo.

parameter_data_type

Tipo di dati del parametro. Per le funzioni Transact-SQL sono consentiti tutti i tipi di dati scalari supportati in Azure Synapse Analytics. Il tipo di dati timestamp (rowversion) non è supportato.

[ = predefinito ]

Valore predefinito per il parametro. Se viene definito un valore default, è possibile eseguire la funzione senza specificare un valore per il parametro corrispondente a tale valore.

Se a un parametro della funzione è associato un valore predefinito, alla chiamata della funzione è necessario specificare la parola chiave DEFAULT per recuperare il valore predefinito. Questo comportamento risulta diverso dall'utilizzo di parametri con valore predefinito nelle stored procedure in cui l'omissione del parametro implica l'utilizzo del valore predefinito.

return_data_type

Valore restituito di una funzione scalare definita dall'utente. Per le funzioni Transact-SQL sono consentiti tutti i tipi di dati scalari supportati in Azure Synapse Analytics. Il tipo di dati timestamp rowversion/non è un tipo supportato. I tipi non scalari cursore e tabella non sono consentiti.

function_body

Serie di istruzioni Transact-SQL. Il function_body non può contenere un'istruzione SELECT e non può fare riferimento ai dati del database. Il function_body non può fare riferimento a tabelle o viste. Il corpo della funzione può chiamare altre funzioni deterministiche, ma non è possibile chiamare funzioni non deterministiche.

Nelle funzioni scalari function_body corrisponde a una serie di istruzioni Transact-SQL che in combinazione restituiscono un valore scalare.

scalar_expression

Specifica il valore scalare restituito dalla funzione scalare.

select_stmt

Istruzione singola SELECT che definisce il valore restituito di una funzione con valori di tabella inline. Per una funzione inline con valori di tabella, non esiste alcun corpo della funzione; la tabella è il set di risultati di una singola SELECT istruzione.

TABELLA

Specifica che il valore restituito della funzione con valori di tabella è una tabella. Alle funzioni con valori di tabella è possibile passare solo costanti e @local_variables.

Nelle funzioni CONF inline (anteprima), il valore restituito TABLE viene definito tramite una singola SELECT istruzione. Alle funzioni inline non sono associate variabili restituite.

<function_option>

Specifica che la funzione dispone di una o più delle opzioni seguenti.

SCHEMABINDING

Specifica che la funzione è associata agli oggetti di database a cui fa riferimento. Quando la clausola SCHEMABINDING viene specificata, non è possibile apportare agli oggetti di base modifiche che hanno effetto sulla definizione della funzione. È necessario prima modificare o eliminare la definizione della funzione per rimuovere le dipendenze dall'oggetto da modificare.

L'associazione della funzione agli oggetti cui fa riferimento viene rimossa solo quando viene eseguita una delle azioni seguenti:

  • La funzione viene eliminata.

  • La funzione viene modificata tramite l'istruzione ALTER senza specificare l'opzione SCHEMABINDING.

Una funzione può essere associata a uno schema solo se vengono soddisfatte le condizioni seguenti:

  • Le funzioni definite dall'utente a cui la funzione fa riferimento sono anch'esse associate a uno schema.

  • Alle funzioni e alle altre funzioni definite dall'utente a cui fa riferimento la funzione viene fatto riferimento tramite un nome composto da una o due parti.

  • Alle funzioni predefinite e alle altre funzioni definite dall'utente nello stesso database è possibile fare riferimento solo all'interno del corpo di funzioni definite dall'utente.

  • L'utente che ha eseguito l'istruzione dispone dell'autorizzazione CREATE FUNCTION REFERENCES per gli oggetti di database a cui fa riferimento la funzione.

Per rimuovere SCHEMABINDING, usare ALTER.

RESTITUISCE NULL IN INPUT NULL | CHIAMATA SU INPUT NULL

Specifica l'attributo OnNULLCall di una funzione con valori scalari. Se non specificato, CALLED ON NULL INPUT è implicito per impostazione predefinita e il corpo della funzione viene eseguito anche se NULL viene passato come argomento.

Procedure consigliate

Se una funzione definita dall'utente non viene creata tramite la clausola SCHEMABINDING, le modifiche apportate agli oggetti sottostanti possono influire sulla definizione della funzione e produrre risultati imprevisti quando viene richiamata. È consigliabile specificare la WITH SCHEMABINDING clausola durante la creazione della funzione. In questo modo, gli oggetti a cui si fa riferimento nella definizione della funzione possono essere modificati solo se viene modificata anche la funzione.

Interoperabilità

In una funzione a valori scalari sono valide le istruzioni seguenti:

  • Istruzioni di assegnazione.

  • Istruzioni per il controllo di flusso, escluse le istruzioni TRY...CATCH.

  • Istruzioni DECLARE che definiscono le variabili dati locali.

In una funzione inline con valori di tabella (anteprima) è consentita una sola istruzione SELECT.

Limiti

Non è possibile utilizzare funzioni definite dall'utente per eseguire azioni che modificano lo stato del database.

È possibile nidificare le funzioni definite dall'utente, ovvero una funzione definita dall'utente ne può richiamare un'altra. Il livello di nidificazione aumenta all'avvio della funzione richiamata e diminuisce al termine dell'esecuzione della funzione. Se viene superato il livello massimo di nidificazioni, l'intera sequenza di funzioni chiamanti ha esito negativo. In Microsoft Fabric Data Warehouse le funzioni definite dall'utente possono essere annidate fino a cinque livelli.

Gli oggetti, incluse le funzioni, non possono essere creati nel master database del pool SQL serverless in Azure Synapse Analytics.

Metadati UFX

Nella sezione seguente vengono elencate le viste del catalogo di sistema usate per restituire i metadati sulle funzioni definite dall'utente.

  • sys.sql_modules: visualizza la definizione di Transact-SQL funzioni definite dall'utente. Ad esempio:

    SELECT definition, type   
FROM sys.sql_modules AS m  
JOIN sys.objects AS o   
    ON m.object_id = o.object_id   
    AND type = ('FN');

  • sys.parameters: visualizza informazioni sui parametri definiti nelle funzioni definite dall'utente.

  • sys.sql_expression_dependencies: visualizza gli oggetti sottostanti a cui fa riferimento una funzione.

Autorizzazioni

È necessario disporre dell'autorizzazione CREATE FUNCTION nel database e dell'autorizzazione ALTER per lo schema in cui la funzione è in fase di creazione.

Esempi

R. Usare una funzione scalare-valued definita dall'utente per modificare un tipo di dati

Questa semplice funzione accetta un tipo di dati int come input e restituisce un tipo di dati decimal(10,2) come output.

CREATE FUNCTION dbo.ConvertInput (@MyValueIn int)  
RETURNS decimal(10,2)  
AS  
BEGIN
    DECLARE @MyValueOut int;  
    SET @MyValueOut= CAST( @MyValueIn AS decimal(10,2));  
    RETURN(@MyValueOut);  
END;  
GO  

SELECT dbo.ConvertInput(15) AS 'ConvertedValue';

Nota

Le funzioni scalari non sono disponibili nei pool SQL serverless.

B. Creare una funzione inline con valori di tabella

L'esempio seguente crea una funzione inline con valori di tabella per restituire alcune informazioni chiave nei moduli, applicando un filtro in base al parametro objectType. Include un valore predefinito per restituire tutti i moduli quando la funzione viene chiamata con il DEFAULT parametro . Questo esempio usa alcune delle viste del catalogo di sistema indicate in Metadati.

CREATE FUNCTION dbo.ModulesByType(@objectType CHAR(2) = '%%')
RETURNS TABLE
AS
RETURN
(
    SELECT 
        sm.object_id AS 'Object Id',
        o.create_date AS 'Date Created',
        OBJECT_NAME(sm.object_id) AS 'Name',
        o.type AS 'Type',
        o.type_desc AS 'Type Description', 
        sm.definition AS 'Module Description'
    FROM sys.sql_modules AS sm  
    JOIN sys.objects AS o ON sm.object_id = o.object_id
    WHERE o.type like '%' + @objectType + '%'
);
GO

La funzione può quindi essere chiamata per restituire tutti gli oggetti visualizzazione (V) con:

select * from dbo.ModulesByType('V');

Nota

Le funzioni con valori di tabella inline sono disponibili nei pool SQL serverless, ma sono in anteprima nei pool SQL dedicati.

C. Combinare i risultati di una funzione inline con valori di tabella

Questo semplice esempio usa la funzione inline con valori di tabella creata in precedenza per dimostrare in che modo è possibile combinare i risultati con altre tabelle usando Cross Apply. In questo caso vengono selezionate tutte le colonne da e sys.objects i risultati di ModulesByType per tutte le righe corrispondenti nella type colonna. Per altre informazioni sull'uso di apply, vedere clausola FROM più JOIN, APPLY, PIVOT (Transact-SQL).

SELECT * 
FROM sys.objects o
CROSS APPLY dbo.ModulesByType(o.type);
GO

Nota

Le funzioni con valori di tabella inline sono disponibili nei pool SQL serverless, ma sono in anteprima nei pool SQL dedicati.

Passaggio successivo

Creare funzioni definite dall'utente (motore di database)