sp_control_plan_guide (Transact-SQL)

Aplica-se: SQL Server

O sp_control_plan_guide procedimento armazenado do sistema é usado para descartar, habilitar ou desabilitar um guia de plano.

Convenções de sintaxe de Transact-SQL

Sintaxe

sp_control_plan_guide
    [ @operation = ] { N'DROP [ ALL ]' | N'DISABLE [ ALL ]' | N'ENABLE [ ALL ]' }
    [ , [ @name = ] N'name' ]
[ ; ]

Argumentos

@name [ = ] N'nome'

Especifica o guia de plano que está descartado, habilitado ou desabilitado. @name é sysname, com um padrão de NULL. @name é resolvido para o banco de dados atual. Se não for especificado, o padrão @name .NULL

@operation [ = ] { N'DROP [ ALL ]' | N'DESABILITAR [ TODOS ]' | N'ENABLE [ ALL ]' }

A operação a ser executada no guia de plano especificado em @name. @operation é nvarchar(60), sem padrão.

  • DROP

    Descarta o guia de plano especificado por @name. Depois que um guia de plano é descartado, as execuções futuras de uma consulta anteriormente correspondida pelo guia de plano não são influenciadas pelo guia de plano.

  • DROP ALL

    Descarta todos os guias de plano no banco de dados atual. @name não pode ser especificado quando DROP ALL é especificado.

  • DISABLE

    Desabilita o guia de plano especificado pelo @name. Depois que um guia de plano é desabilitado, as execuções futuras de uma consulta anteriormente correspondida pelo guia de plano não são influenciadas pelo guia de plano.

  • DISABLE ALL

    Desabilita todos os guias de plano no banco de dados atual. @name não pode ser especificado quando DISABLE ALL é especificado.

  • ENABLE

    Habilita o guia de plano especificado por @name. Um guia de plano pode ser correspondido a uma consulta qualificada depois de habilitado. Por padrão, os guias de plano são habilitados no momento em que são criados.

  • ENABLE ALL

    Habilita todos os guias de plano no banco de dados atual. @name não pode ser especificado quando ENABLE ALL é especificado.

Comentários

A tentativa de cancelar ou modificar uma função, procedimento armazenado ou gatilho DML referenciado por um guia de plano, habilitado ou desabilitado, provoca um erro.

A desabilitação de um guia de plano desabilitado ou a habilitação de um guia de plano habilitado não tem nenhum efeito e ocorre sem erro.

Os guias de planos não estão disponíveis em todas as edições do SQL Server. Para obter uma lista de recursos com suporte nas edições do SQL Server, confira Edições e recursos com suporte no SQL Server 2022. No entanto, você pode executar sp_control_plan_guide com a DROP opção ou DROP ALL em qualquer edição do SQL Server.

Permissões

A execução sp_control_plan_guide em um guia de plano do tipo OBJECT (criado especificando @type = '<object>') requer ALTER permissão no objeto referenciado pelo guia de plano. Todos os outros guias de plano exigem ALTER DATABASE permissão.

Exemplos

R. Habilitar, desabilitar e descartar um guia de plano

O exemplo seguinte cria um guia de plano, desabilita-o, habilita-o e o descarta.

--Create a procedure on which to define the plan guide.
IF OBJECT_ID(N'Sales.GetSalesOrderByCountry', N'P') IS NOT NULL
    DROP PROCEDURE Sales.GetSalesOrderByCountry;
GO

CREATE PROCEDURE Sales.GetSalesOrderByCountry (@Country NVARCHAR(60))
AS
BEGIN
    SELECT *
    FROM Sales.SalesOrderHeader AS h
    INNER JOIN Sales.Customer AS c
        ON h.CustomerID = c.CustomerID
    INNER JOIN Sales.SalesTerritory AS t
        ON c.TerritoryID = t.TerritoryID
    WHERE t.CountryRegionCode = @Country;
END
GO

--Create the plan guide.
EXEC sp_create_plan_guide N'Guide3',
    N'SELECT *
    FROM Sales.SalesOrderHeader AS h
    INNER JOIN Sales.Customer AS c
        ON h.CustomerID = c.CustomerID
    INNER JOIN Sales.SalesTerritory AS t
        ON c.TerritoryID = t.TerritoryID
    WHERE t.CountryRegionCode = @Country',
    N'OBJECT',
    N'Sales.GetSalesOrderByCountry',
    NULL,
    N'OPTION (OPTIMIZE FOR (@Country = N''US''))';
GO

--Disable the plan guide.
EXEC sp_control_plan_guide N'DISABLE',
    N'Guide3';
GO

--Enable the plan guide.
EXEC sp_control_plan_guide N'ENABLE',
    N'Guide3';
GO

--Drop the plan guide.
EXEC sp_control_plan_guide N'DROP',
    N'Guide3';
GO

B. Desabilitar todos os guias de plano no banco de dados atual

O exemplo seguinte desabilita todos os guias de plano no banco de dados AdventureWorks2022.

USE AdventureWorks2022;
GO
EXEC sp_control_plan_guide N'DISABLE ALL';