CONTAINSTABLE (Transact-SQL)

Devuelve una tabla con una o más filas para aquellas columnas que contengan 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. Se usa CONTAINSTABLE en una cláusula FROM de una instrucción SELECT de Transact-SQL y se hace referencia a ella como si fuera un nombre de tabla normal. .It realiza una búsqueda de texto completo en SQL Server en las columnas indizadas de texto completo que contienen tipos de datos basados en caracteres.

CONTAINSTABLE es útil para los mismos tipos de coincidencias que el predicado CONTAINS y usa las mismas condiciones de búsqueda que CONTAINS.

A diferencia de CONTAINS, las consultas que usan CONTAINSTABLE devuelven un valor de clasificación por relevancia (RANK) y un valor de clave de texto completo (KEY) por cada fila.

[!NOTA]

Para obtener información acerca de los formatos de búsqueda de texto completo que SQL Server admite, vea Consultar con búsqueda de texto completo.

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> 
    | <generic_proximity_term> 
    | <custom_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 ] ) 

<generic_proximity_term> ::= 
     { <simple_term> | <prefix_term> } { { { NEAR | ~ } 
     { <simple_term> | <prefix_term> } } [ ...n ] }

<custom_proximity_term> ::= 
  NEAR ( 
     {
        { <simple_term> | <prefix_term> } [ ,…n ]
     |
        ( { <simple_term> | <prefix_term> } [ ,…n ] ) 
      [, <maximum_distance> [, <match_order> ] ]
     }
       ) 

      <maximum_distance> ::= { integer | MAX }
      <match_order> ::= { TRUE | FALSE } 

<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, puede incluirse solo una tabla base indizada 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 se pueden especificar varias columnas, separadas por una coma. column_list debe ir 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 LANGUAGE language_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 ir 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 superar los 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 los recursos de idioma neutro, especifique 0x0 como language_term.

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

• <contains_search_condition>
  Especifica el texto que se va a buscar 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 y las funciones de texto completo 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 generada 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 clasificación 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 de la tabla.

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

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 clasificación

En el ejemplo siguiente se buscan todos los nombres de producto que contienen las palabras “frame”, “wheel” o “tire” y se asignan ponderaciones distintas a cada palabra. Por cada fila devuelta que cumpla estos criterios de búsqueda, se muestra la precisión relativa (el valor de clasificación) de la coincidencia. Además, las filas cuyo valor de clasificación es más alto se devuelven primero.

USE AdventureWorks2012
GO

SELECT FT_TBL.Name, KEY_TBL.RANK
    FROM Production.Product AS FT_TBL 
        INNER JOIN CONTAINSTABLE(Production.Product, Name, 
        'ISABOUT (frame WEIGHT (.8), 
        wheel WEIGHT (.4), tire WEIGHT (.2) )' ) AS KEY_TBL
            ON FT_TBL.ProductID = KEY_TBL.[KEY]
ORDER BY KEY_TBL.RANK DESC
GO

B.Devolver valores de clasificación más altos que un valor especificado

En el ejemplo siguiente se usa NEAR para buscar “bracket” y “reflector” cercanos entre sí en la columna Production.Document de la base de datos AdventureWorks2008. Solo se devuelven las filas cuyo valor de distancia sea igual o superior a 50.

USE AdventureWorks2012
GO

SELECT DocumentNode, Title, DocumentSummary
FROM Production.Document AS DocTable 
INNER JOIN CONTAINSTABLE(Production.Document, Document,
  'NEAR(bracket, reflector)' ) AS KEY_TBL
  ON DocTable.DocumentNode = KEY_TBL.[KEY]
WHERE KEY_TBL.RANK > 50
ORDER BY KEY_TBL.RANK DESC
GO

[!NOTA]

Si en una consulta de texto completo no se especifica un entero como la distancia máxima, un documento que contiene solo los aciertos cuyo intervalo es mayor que 100 términos lógicos no cumplirá los requisitos NEAR, y la clasificación será 0.

C.Devolver los 5 mejores resultados utilizando top_n_by_rank

En el ejemplo siguiente se devuelve la descripción de los 5 productos más destacados, donde la columna Description contiene la palabra “aluminum” cerca de la palabra “light” o de la palabra “lightweight”.

USE AdventureWorks2012
GO

SELECT FT_TBL.ProductDescriptionID,
   FT_TBL.Description, 
   KEY_TBL.RANK
FROM Production.ProductDescription AS FT_TBL INNER JOIN
   CONTAINSTABLE (Production.ProductDescription,
      Description, 
      '(light NEAR aluminum) OR
      (lightweight NEAR aluminum)',
      5
   ) AS KEY_TBL
   ON FT_TBL.ProductDescriptionID = KEY_TBL.[KEY]
GO

GO

D.Especificar el argumento LANGUAGE

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

USE AdventureWorks2012
GO

SELECT FT_TBL.ProductDescriptionID,
   FT_TBL.Description, 
   KEY_TBL.RANK
FROM Production.ProductDescription AS FT_TBL INNER JOIN
   CONTAINSTABLE (Production.ProductDescription,
      Description, 
      '(light NEAR aluminum) OR
      (lightweight NEAR aluminum)',
      LANGUAGE N'English',
      5
   ) AS KEY_TBL
   ON FT_TBL.ProductDescriptionID = KEY_TBL.[KEY]
GO

[!NOTA]

El argumento language_term no es necesario para usar top_n_by_rank.

Vea también

Tasks

Crear consultas de búsqueda de texto completo (Visual Database Tools)

Referencia

CONTAINS (Transact-SQL)

SELECT (Transact-SQL)

FROM (Transact-SQL)

Conceptos

Limitar los resultados de la búsqueda con RANK

Consultar con búsqueda de texto completo

Consultar con búsqueda de texto completo