All Products
Search

This Product

    Tablestore:Create a mapping table

    Document Center

    Tablestore:Create a mapping table

    Last Updated:Sep 29, 2026

    Tablestore SDK for PHP creates a mapping table for an existing table or search index to enable SQL access to data.

    Usage notes

    SQL query is supported in Tablestore SDK for PHP V5.1.0 and later. Make sure that a supported version is installed.

    For the version history of Tablestore SDK for PHP, see Version history of Tablestore SDK for PHP.

    Prerequisites

    Parameters

    SQLQueryRequest contains the following parameter.

    Name

    Type

    Description

    query (required)

    String

    The CREATE TABLE statement that defines the mapping table name, fields, primary key, and query engine. Data table mappings and search index mappings use different syntax.

    Examples

    Note

    This topic describes how to create a mapping table for a table. If you want to create a mapping table for a search index, replace the SQL statement in the sample code with the SQL statement used to create a mapping table for a search index.

    The following example shows how to use the CREATE TABLE `tableName` (`PK0` BIGINT(20),`PK1` VARCHAR(1024),`geo` MEDIUMTEXT,`boolean` BOOL,`array` MEDIUMTEXT,`double` DOUBLE,`text` MEDIUMTEXT,`keyword` MEDIUMTEXT,`nested` MEDIUMTEXT,`long` BIGINT(20),PRIMARY KEY(`PK0`,`PK1`)); statement to create a mapping table for the tableName table.

    $request = array(
    'query' => 'CREATE TABLE `tableName` (`PK0` BIGINT(20),`PK1` VARCHAR(1024),`geo` MEDIUMTEXT,`boolean` BOOL,`array` MEDIUMTEXT,`double` DOUBLE,`text` MEDIUMTEXT,`keyword` MEDIUMTEXT,`nested` MEDIUMTEXT,`long` BIGINT(20),PRIMARY KEY(`PK0`,`PK1`));',
);
$response = $otsClient->sqlQuery($request);
print json_encode($response, JSON_PRETTY_PRINT);

    FAQ

    What do I do if the "Table 'instancename.tablename' doesn't exist ?" error message is returned when I create a mapping table?

    • Possible cause

      The table for which you want to create a mapping table does not exist.

    • Solution

      You can execute the CREATE TABLE statement in SQL to create a mapping table only for an existing table or search index. Make sure that the table or search index for which you want to create a mapping table exists.

    What do I do if the "Table 'instancename.tablename' already exist?" error message is returned when I create a mapping table?

    • Possible cause

      A mapping table is created for the table.

      • The user manually created a mapping table for the table.

      • Tablestore automatically created a mapping table for the table. If you directly use SQL statements (such as DESCRIBE, SELECT, etc.) to query data in a data table without creating a mapping table for the data table, Tablestore automatically creates a mapping table for the data table. The automatically created mapping table only contains the primary key columns and predefined columns of the data table. You cannot update the attribute columns of the mapping table.

    • Solution

      You can execute the DESCRIBE statement to query the schema of the mapping table. If the schema does not meet your business requirements, you can update the attribute columns of the mapping table. If the mapping table is automatically created by Tablestore, you cannot update the attribute columns. In this case, you can delete the mapping table and create a new one if you are sure that your business is not affected after you delete the mapping table.

    Note

    For common errors and solutions of the SQL query feature, see Troubleshoot common SQL query errors.

    References