CONTAINSTABLE (Transact-SQL)

Devuelve una tabla con una o más filas para aquellas columnas que contengan datos de tipo carácter en las que haya coincidencias exactas o aproximadas (menos precisas) con palabras simples o frases, palabras próximas a otra dada (dentro de una cierta distancia) o bien coincidencias ponderadas. Solamente puede hacerse referencia a CONTAINSTABLE en una cláusula FROM de una instrucción SELECT como si fuera un nombre de tabla normal.

Las consultas que utilizan CONTAINSTABLE especifican consultas de texto completo de tipo CONTAINS que devuelven un valor de clasificación por porcentaje de aciertos (RANK) y un valor de clave de texto (KEY) por cada fila. La función CONTAINSTABLE utiliza las mismas condiciones de búsqueda que el predicado CONTAINS.

Convenciones de sintaxis de Transact-SQL

Sintaxis

CONTAINSTABLE ( table , { column_name | (column_list ) | * } , ' < contains_search_condition > ' 
     [ , LANGUAGE language_term] 
  [ , top_n_by_rank ] 
          ) 
< contains_search_condition > ::= 
    { < simple_term > 
    | < prefix_term > 
    | < generation_term > 
    | < proximity_term > 
    |  < weighted_term > 
    } 
    | { ( < contains_search_condition > ) 
    { { AND | & } | { AND NOT | &! } | { OR | | } } 
     < contains_search_condition > [ ...n ] 
    }
< simple_term > ::= 
          word | " phrase "
< prefix term > ::= 
     { "word * " | "phrase *" } 
< generation_term > ::= 
     FORMSOF ( { INFLECTIONAL | THESAURUS } , < simple_term > [ ,...n ] ) 
< proximity_term > ::= 
     { < simple_term > | < prefix_term > } 
     { { NEAR | ~ } { < simple_term > | < prefix_term > } } [ ...n ] 
< weighted_term > ::= 
     ISABOUT
        ( { { 
  < simple_term > 
  | < prefix_term > 
  | < generation_term > 
  | < proximity_term > 
  } 
   [ WEIGHT ( weight_value ) ] 
   } [ ,...n ] 
        )

Argumentos

• table
  Es el nombre de una tabla que se ha sometido a una indización de texto completo. table puede ser el nombre de un objeto de base de datos de una, dos, tres o cuatro partes. Al consultar una vista, solamente puede incluirse una tabla base con índices de texto completo.

  table no puede especificar un nombre de servidor y no puede utilizarse para realizar consultas en servidores vinculados.

• column_name
  Es el nombre de una o más columnas indizadas para la búsqueda de texto completo. Las columnas pueden ser de tipo char, varchar, nchar, nvarchar, text, ntext, image, xml, varbinary o varbinary(max).

• column_list
  Indica que pueden especificarse varias columnas, separadas por una coma. column_list debe incluirse entre paréntesis. A menos que se especifique language_term, el idioma de todas las columnas de column_list debe ser el mismo.

• *
  Especifica que todas las columnas indizadas de texto completo de table deben utilizarse en la condición de búsqueda. A menos que se especifique language_term, el idioma de todas las columnas de la tabla debe ser el mismo.

• LANGUAGE language_term
  Es el idioma cuyos recursos se utilizarán en la separación de palabras, la lematización, los diccionarios de sinónimos y la eliminación de palabras irrelevantes (o palabras vacías) como parte de la consulta. Este parámetro es opcional y puede especificarse como un valor hexadecimal, un entero o una cadena correspondiente al identificador de configuración regional (LCID) de un idioma. Si se especifica language_term, el idioma que representa se aplica a todos los elementos de la condición de búsqueda. Si no se especifica ningún valor, se utiliza el idioma de texto completo de la columna.

  Si se almacenan juntos documentos de idiomas diferentes como objetos binarios grandes (BLOB) en una sola columna, el identificador de configuración regional (LCID) de un documento determinado determina qué idioma se usa para indizar su contenido. Al consultar este tipo de columna, especificar LANGUAGElanguage_term puede aumentar la probabilidad de encontrar una coincidencia acertada.

  Si el valor especificado es una cadena, language_term corresponde al valor de columna alias de la vista de compatibilidad sys.syslanguages. La cadena debe incluirse entre comillas simples, como en 'language_term'. Si el valor especificado es un entero, language_term es el LCID real que identifica el idioma. Si se especifica como un valor hexadecimal, language_term es 0x seguido del valor hexadecimal del LCID. El valor hexadecimal no puede tener más de ocho dígitos, incluidos los ceros a la izquierda.

  Si el valor está en formato DBCS (juego de caracteres de doble byte), Microsoft SQL Server lo convertirá a Unicode.

  Si el idioma especificado no es válido o no hay recursos instalados que se correspondan con dicho idioma, SQL Server devuelve un error. Para utilizar recursos de idioma neutro, especifique 0x0 como language_term.

• top_n_by_rank
  Especifica que solamente se devuelvan las ncoincidencias con una clasificación más alta, en orden descendente. Solamente se aplica cuando se especifica un valor entero, n. Si top_n_by_rank se combina con otros parámetros, la consulta podría devolver menos filas de las que en realidad coinciden con todos los predicados. top_n_by_rank permite aumentar el rendimiento de las consulta recuperando solamente las coincidencias más relevantes.

• <contains_search_condition>
  Especifica el texto que va a buscarse en column_name y las condiciones para obtener coincidencias. Para obtener información acerca de las condiciones de búsqueda, vea CONTAINS (Transact-SQL).

Comentarios

Los predicados de texto completo y las funciones operan en una única tabla, que se obtiene del predicado FROM. Para buscar en varias tablas, utilice una tabla combinada en la cláusula FROM a fin de buscar en un conjunto de resultados que sea el producto de dos o más tablas.

La tabla devuelta tiene una columna denominada KEY que contiene valores de claves de texto completo. Todas las tablas indizadas de texto completo tienen una columna cuyos valores se garantiza que son únicos y los valores devueltos en la columna KEY son los valores de clave de texto completo de las filas que cumplen los criterios de selección especificados en la condición de búsqueda CONTAINS. La propiedad TableFulltextKeyColumn obtenida mediante la función OBJECTPROPERTY, proporciona la identidad de esta columna de clave única. Para obtener el identificador de la columna asociada a la clave de texto completo del índice de texto completo, utilice sys.fulltext_indexes. Para obtener más información, vea sys.fulltext_indexes (Transact-SQL).

Para obtener las filas que desee de la tabla original, especifique una combinación con las filas de CONTAINSTABLE. La forma típica de la cláusula FROM de una instrucción SELECT que utiliza CONTAINSTABLE es la siguiente:

SELECT select_list
FROM table AS FT_TBL INNER JOIN
   CONTAINSTABLE(table, column, contains_search_condition) AS KEY_TBL
   ON FT_TBL.unique_key_column = KEY_TBL.[KEY]

La tabla generado por CONTAINSTABLE incluye una columna denominada RANK. La columna RANK es un valor (comprendido entre 0 y 1000) que indica para cada fila el grado en que cumple los criterios de selección. Este valor de rango suele utilizarse en las instrucciones SELECT de una de estas maneras:

• En la cláusula ORDER BY, para devolver las filas de mayor valor al principio.

• En la lista de selección, para ver el valor de rango asignado a cada fila.

CONTAINSTABLE no se reconoce como palabra clave si el nivel de compatibilidad es inferior a 70. Para obtener más información, vea sp_dbcmptlevel (Transact-SQL).

Permisos

Solamente disponen de permisos de ejecución los usuarios que tienen los permisos SELECT adecuados en la tabla o en las columnas de la tabla a las que se hace referencia.

Ejemplos

A. Devolver valores de rango mediante CONTAINSTABLE

En este ejemplo se buscan todos los nombres de productos que contienen las palabras “breads”, “fish” o “beers”; se asignan pesos distintos a cada palabra. Por cada fila devuelta que cumpla los criterios de la búsqueda, se muestra la precisión relativa (valor de clasificación) de la coincidencia. Además, las filas cuyo valor de clasificación es más alto se devuelven primero.

USE Northwind;
GO
SELECT FT_TBL.CategoryName, FT_TBL.Description, KEY_TBL.RANK
    FROM Categories AS FT_TBL 
        INNER JOIN CONTAINSTABLE(Categories, Description, 
        'ISABOUT (breads weight (.8), 
        fish weight (.4), beers weight (.2) )' ) AS KEY_TBL
            ON FT_TBL.CategoryID = KEY_TBL.[KEY]
ORDER BY KEY_TBL.RANK DESC;
GO

B. Devolver valores de rango más altos que un valor especificado mediante CONTAINSTABLE

En este ejemplo se devuelven la descripción y el nombre de categoría de todas las categorías de alimentos en las que la columna Description contiene las palabras "sweet and savory" cerca de la palabra sauces o de la palabra candies. Todas las filas cuyo nombre de categoría es Seafood no se devuelven. Solamente se devuelven las filas cuyo valor de rango es igual o superior a 2.

USE Northwind;
GO
SELECT FT_TBL.Description, FT_TBL.CategoryName, KEY_TBL.RANK
FROM Categories AS FT_TBL 
    INNER JOIN CONTAINSTABLE (Categories, Description, 
        '("sweet and savory" NEAR sauces) OR
        ("sweet and savory" NEAR candies)'
        ) AS KEY_TBL
        ON FT_TBL.CategoryID = KEY_TBL.[KEY]
WHERE KEY_TBL.RANK > 2
    AND FT_TBL.CategoryName <> 'Seafood'
ORDER BY KEY_TBL.RANK DESC;
GO

C. Devolver los 10 mejores resultados utilizando CONTAINSTABLE y top_n_by_rank

En este ejemplo se devuelven la descripción y el nombre de categoría de las 10 categorías superiores de alimentos donde la columna Description contiene las palabras "sweet and savory" cerca de la palabra "sauces" o de la palabra "candies".

USE Northwind;
SELECT FT_TBL.Description, FT_TBL.CategoryName , KEY_TBL.RANK
FROM Categories AS FT_TBL 
    INNER JOIN CONTAINSTABLE (Categories, Description, 
        '("sweet and savory" NEAR sauces) OR
        ("sweet and savory" NEAR candies)', 10)
        AS KEY_TBL
        ON FT_TBL.CategoryID = KEY_TBL.[KEY]

GO

D. Especificar el argumento LANGUAGE

En el siguiente ejemplo se muestra la forma de utilizar el argumento LANGUAGE.

USE Northwind;
SELECT FT_TBL.Description , FT_TBL.CategoryName , KEY_TBL.RANK
FROM dbo.Categories AS FT_TBL 
    INNER JOIN CONTAINSTABLE (dbo.Categories, Description, 
        '("sweet and savory" NEAR sauces) OR
        ("sweet and savory" NEAR candies)',LANGUAGE N'English', 10) 
        AS KEY_TBL
        ON FT_TBL.CategoryID = KEY_TBL.[KEY];

Nota

El argumento LANGUAGE language_term no es necesario para usar top_n_by_rank.

Vea también

Tasks

Cómo crear un catálogo de texto (SQL Server Management Studio)

Cómo iniciar el Asistente para indización de texto completo (SQL Server Management Studio)

Cómo crear consultas de búsqueda de texto completo (Visual Database Tools)

Referencia

CREATE FULLTEXT CATALOG (Transact-SQL)

CREATE FULLTEXT INDEX (Transact-SQL)

CONTAINS (Transact-SQL)

Funciones de conjuntos de filas (Transact-SQL)

SELECT (Transact-SQL)

WHERE (Transact-SQL)

Conceptos

Introducción a la búsqueda de texto completo

Introducción a la indización de texto completo

Información general de funciones y predicados de texto completo

Aspectos básicos de las combinaciones

Consultar SQL Server mediante la búsqueda de texto