Tablestore:Especifique identificadores de série temporal personalizados e campos de dados personalizados como colunas de chave primária

Especificar identificadores de série temporal personalizados

Definir identificadores de série temporal personalizados é útil em cenários que exigem posicionamento temporal preciso, consultas por intervalo, análise de tendências e associação de eventos. Os itens a seguir detalham esses casos de uso:

• Solução de problemas e análise de causa raiz

  Em operações de TI e monitoramento de equipamentos industriais, identificadores personalizados permitem marcar com precisão o momento das falhas. Ao correlacionar essas informações com outros dados temporais (como status do dispositivo e logs), torna-se mais rápido localizar as causas dos problemas para a análise de causa raiz.

• Análise de comportamento do usuário

  Em aplicações de internet, o registro de horários de login, duração de visualização de páginas e sequências de operações viabiliza a análise de períodos de atividade, duração de sessões e caminhos de navegação. Essa abordagem orientada por dados facilita a otimização da experiência do usuário e recomendações inteligentes de conteúdo.

• Auditoria de transações financeiras

  No setor financeiro, cada transação exige um timestamp exato. Identificadores personalizados garantem não apenas a sequência e integridade das transações, mas também suportam análises antifraude, como identificação de padrões anômalos e rastreamento de fluxos financeiros.

Ao adotar identificadores de série temporal personalizados, você agrupa, filtra e analisa dados temporais de maneira flexível, possibilitando gestão granular e insights mais profundos em diversos contextos de negócios.

Especificar campos de dados personalizados como colunas de chave primária

Para armazenar múltiplas linhas de dados de série temporal com os mesmos identificadores e timestamp, defina campos de dados personalizados como colunas de chave primária da sua tabela. Veja a seguir os cenários aplicáveis:

• Análise de associação de eventos

  Em análises complexas, pode ser necessário associar dados temporais com base em campos além dos identificadores padrão. Definir campos personalizados como chave primária permite localizar rapidamente dados de um dispositivo específico em timestamps determinados, sendo ideal para solução de problemas e análise comportamental.

• Indexação multidimensional

  Para aplicações avançadas de bancos de dados temporais que exigem consultas e filtragens multidimensionais, usar campos personalizados como chave primária aumenta a eficiência das consultas. Essa estratégia facilita a localização precisa de dados relevantes, especialmente no processamento de grandes volumes de informações.

• Gestão de dados temporais multilocatário

  Ao fornecer serviços de armazenamento de séries temporais para vários clientes, utilize o id do locatário como uma das colunas de chave primária, formando uma chave composta com o timestamp. Isso garante isolamento de dados e acesso eficiente para cada locatário.

Usar o console do Tablestore

1. Ao criar a tabela de série temporal, especifique os identificadores personalizados. Consulte Gerenciar tabelas de série temporal.

2. Escreva dados na tabela utilizando os identificadores personalizados.

   Durante a escrita, o cliente envia os campos dos identificadores personalizados ao servidor Tablestore como pares chave-valor. O servidor extrai primeiramente o nome da métrica e a fonte de dados; os pares restantes tornam-se tags da série temporal. Para detalhes, visualize Escrever dados de série temporal.

   Importante

   Se a tabela for criada sem o campo _tags nos identificadores personalizados, mas ainda existirem pares chave-valor remanescentes (após excluir métrica, fonte e campos personalizados) durante a escrita, a operação falhará.

3. Leia dados da tabela de série temporal.

   1. Crie uma tabela de mapeamento SQL para a tabela de série temporal. Consulte Criar tabelas de mapeamento no modelo de múltiplos valores para tabelas de série temporal.

      1. Na página Manage Time Series Table, clique em na aba Query by Executing SQL Statement.

      2. À esquerda da aba Query by Executing SQL Statement, clique em no ícone + ao lado do nome da instância do modelo TimeSeries.

      3. Na caixa de diálogo Create Mapping Table, configure os parâmetros descritos na tabela abaixo.

         Parâmetro	Descrição
         Table Name	Nome da tabela de série temporal.
         Mapping Table Name	Nome da tabela de mapeamento. Nota Ao criar uma tabela de mapeamento SQL para uma tabela de série temporal, o sistema adiciona automaticamente o prefixo time series table name:: ao nome da tabela de mapeamento.
         Enable Analytical Store	O recurso analytical store destina-se a cenários de retenção prolongada e análise de dados temporais. Ele permite armazenamento com custos reduzidos e consultas eficientes. Para mais informações, consulte Analytical store. Por padrão, a opção Enable Analytical Store está desativada. Configure conforme sua necessidade. Caso não pretenda usar o analytical store, mantenha a configuração padrão do parâmetro Enable Analytical Store. Para reduzir custos de armazenamento ou realizar análises eficientes, assegure-se de que um analytical store foi criado e que a opção Enable Analytical Store está ativada. Importante O analytical store é suportado nas regiões China (Hangzhou), China (Shanghai), China (Beijing) e China (Zhangjiakou). Crie a instância do modelo TimeSeries em uma dessas regiões para utilizá-lo. Consulte Criar uma instância para o modelo TimeSeries. Se você criar uma tabela de mapeamento com Enable Analytical Store ativado, será necessário excluir simultaneamente a tabela de mapeamento ao remover o analytical store. Caso contrário, a exclusão do analytical store falhará.

      4. Clique em Generate SQL Statement. O sistema gerará automaticamente a instrução SQL para criação da tabela de mapeamento.

         Após definir identificadores personalizados, inclua tanto esses identificadores quanto os campos de dados personalizados (usados como chave primária na tabela original) como colunas de chave primária na tabela de mapeamento SQL.

      5. Clique em Execute SQL Statement(F8).

   2. Execute a instrução SELECT para consultar dados. Consulte Consultar dados.

      Insira a instrução SQL no editor do console e clique em Execute SQL Statement(F8).

      O exemplo abaixo demonstra como consultar informações de séries temporais onde cpu_usage ultrapassa 90,0, utilizando a tabela de mapeamento cpu::ts1:

      SELECT `host`, `processor`, `_tags` , `_time` FROM `cpu::ts1` WHERE cpu_usage > 90.0;

Usar os SDKs do Tablestore

Este exemplo utiliza o Tablestore SDK for Java.

1. Especifique os identificadores personalizados ao criar a tabela de série temporal.

   O código abaixo exemplifica a criação de uma tabela sem analytical store e com identificadores personalizados:

   private static void createTimeseriesTable(TimeseriesClient client) {
       TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta("");
       timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(-1));
       // Specify custom time series identifiers. The host field stores the metric name, the processor field stores the data source, and the _tags field stores the tags.
       timeseriesTableMeta.addTimeseriesKey("host");
       timeseriesTableMeta.addTimeseriesKey("processor");
       timeseriesTableMeta.addTimeseriesKey("_tags");
       CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
       request.setEnableAnalyticalStore(false);
       client.createTimeseriesTable(request);
   }

2. Escreva dados na tabela seguindo os identificadores personalizados.

   O cliente transmite os campos dos identificadores personalizados ao servidor Tablestore como pares chave-valor. O servidor extrai métrica e fonte de dados, convertendo os pares restantes em tags da série temporal.

   Importante

   Se a tabela não possuir o campo _tags nos identificadores personalizados e sobrarem pares chave-valor após a extração de métrica, fonte e campos customizados durante a escrita, a operação resultará em erro.

   O trecho a seguir mostra como inserir três linhas de dados usando identificadores personalizados.

   private static void putTimeseriesData(TimeseriesClient client) {
       long timeInUs = System.currentTimeMillis() * 1000;
       List rows = new ArrayList();
       for (int i = 0; i < 3; i++) {
           Map tags = new HashMap<>();
           // Add fields of the custom time series identifiers.
           tags.put("host", "host_" + i);
           tags.put("processor", String.valueOf(i));
           // Key-value pairs that do not correspond to custom time series identifiers are used as tags of the time series.
           tags.put("region", "hangzhou");
            TimeseriesKey timeseriesKey = new TimeseriesKey("", "", tags);
           TimeseriesRow row = new TimeseriesRow(timeseriesKey, timeInUs);
           row.addField("cpu_usage", ColumnValue.fromDouble(10.0));
           row.addField("cpu_sys", ColumnValue.fromDouble(5.0));
           rows.add(row);
       }
       String tableName = "";
       PutTimeseriesDataRequest putTimeseriesDataRequest = new PutTimeseriesDataRequest(tableName);
       putTimeseriesDataRequest.setRows(rows);
       client.putTimeseriesData(putTimeseriesDataRequest);
   }

   A tabela abaixo exibe os dados gravados com sucesso.

   host	processor	_tags	_time	cpu_usage	cpu_sys
   host_0	0	["region=hangzhou"]	1712476524000000	10,0	5,0
   host_1	1	["region=hangzhou"]	1712476524000000	10,0	5,0
   host_2	2	["region=hangzhou"]	1712476524000000	10,0	5,0

3. Utilize instruções SQL para ler dados da tabela.

   1. Crie uma tabela de mapeamento SQL. Consulte Criar tabelas de mapeamento no modelo de múltiplos valores para tabelas de série temporal.

      Inclua os campos dos identificadores personalizados e o campo de timestamp como chaves primárias na tabela de mapeamento SQL.

      Exemplo de configuração:

      CREATE TABLE `cpu::ts1` (
          `host` VARCHAR(1024),
          `processor` VARCHAR(1024),
          `_tags` VARCHAR(1024),
          `_time` BIGINT(20),
          `cpu_usage` DOUBLE,
          `cpu_sys` DOUBLE,
          PRIMARY KEY(`host`,`processor`,`_tags`,`_time`)
      );

   2. Execute a instrução SELECT para consultar dados. Consulte Consultar dados.

      O exemplo a seguir consulta séries temporais com cpu_usage maior que 90,0 usando a tabela de mapeamento cpu::ts1:

      SELECT `host`, `processor`, `_tags` , `_time` FROM `cpu::ts1` WHERE cpu_usage > 90.0;

Usar o console do Tablestore

1. Defina os campos de dados personalizados como colunas de chave primária ao criar a tabela. Consulte Gerenciar tabelas de série temporal.

2. Grave dados na tabela de série temporal.

   Os campos definidos como chave primária não podem ficar vazios durante a escrita. Essa configuração permite armazenar múltiplas linhas com os mesmos identificadores e timestamp. Visualize Escrever dados de série temporal.

3. Leia dados da tabela de série temporal.

   1. Crie uma tabela de mapeamento SQL. Consulte Criar tabelas de mapeamento no modelo de múltiplos valores para tabelas de série temporal.

      1. Na página Manage Time Series Table, acesse a aba Query by Executing SQL Statement.

      2. No lado esquerdo da aba Query by Executing SQL Statement, clique em no ícone + próximo à instância do modelo TimeSeries.

      3. Configure os parâmetros na caixa de diálogo Create Mapping Table conforme a tabela a seguir.

         Parâmetro	Descrição
         Table Name	Nome da tabela de série temporal.
         Mapping Table Name	Nome da tabela de mapeamento. Nota O sistema prefixa automaticamente o nome da tabela de mapeamento com time series table name:: durante a criação.
         Enable Analytical Store	Utilize o analytical store para reter dados temporais por longos períodos e realizar análises. Esse recurso reduz custos e otimiza consultas. Saiba mais em Analytical store. A opção Enable Analytical Store vem desativada por padrão. Ajuste conforme necessário. Mantenha o padrão se não for utilizar o analytical store para armazenamento e análise. Ative a opção Enable Analytical Store e garanta a existência de um analytical store para obter custos menores e análises eficientes. Importante Disponível nas regiões China (Hangzhou), China (Shanghai), China (Beijing) e China (Zhangjiakou). Crie a instância TimeSeries nessas localidades. Visualize Criar uma instância para o modelo TimeSeries. Ao excluir um analytical store associado a uma tabela de mapeamento com Enable Analytical Store ativo, remova também a tabela de mapeamento. A falta dessa ação impede a exclusão do analytical store.

      4. Clique em Enable Analytical Store para gerar automaticamente o comando SQL de criação.

         Certifique-se de incluir os identificadores de série temporal e os campos personalizados (definidos como chave primária na tabela original) como chaves primárias na tabela de mapeamento SQL.

      5. Clique em Generate SQL Statement.

   2. Execute a instrução SELECT para consultar dados. Consulte Consultar dados.

      Digite o SQL no editor do console e clique em Execute SQL Statement(F8).

      Exemplo de consulta de séries com cpu_usage acima de 90,0 usando a tabela de mapeamento cpu::ts1:

      SELECT `host`, `processor`, `_tags` , `_time` FROM `cpu::ts1` WHERE cpu_usage > 90.0;

Usar os SDKs do Tablestore

Exemplo baseado no Tablestore SDK for Java.

1. Defina os campos personalizados como chave primária durante a criação da tabela.

   O código abaixo cria uma tabela sem analytical store e configura um campo personalizado como chave primária:

   private static void createTimeseriesTable(TimeseriesClient client) {
       TimeseriesTableMeta timeseriesTableMeta = new TimeseriesTableMeta("");
       timeseriesTableMeta.setTimeseriesTableOptions(new TimeseriesTableOptions(-1));
       // Specify custom data fields as the primary key columns.
       timeseriesTableMeta.addFieldPrimaryKey("processor", PrimaryKeyType.INTEGER);
       CreateTimeseriesTableRequest request = new CreateTimeseriesTableRequest(timeseriesTableMeta);
       request.setEnableAnalyticalStore(false);
       client.createTimeseriesTable(request);
   }

2. Grave dados na tabela de série temporal.

   Preencha obrigatoriamente os campos definidos como chave primária. Isso possibilita o armazenamento de múltiplas linhas com os mesmos identificadores e timestamp.

   Exemplo de escrita de três linhas compartilhando identificadores e timestamp:

   private static void putTimeseriesData(TimeseriesClient client) {
       long timeInUs = System.currentTimeMillis() * 1000;
       List rows = new ArrayList();
       for (int i = 0; i < 3; i++) {
           Map tags = new HashMap<>();
           tags.put("region", "hangzhou");
            TimeseriesKey timeseriesKey = new TimeseriesKey("cpu", "host_" + i, tags);
           TimeseriesRow row = new TimeseriesRow(timeseriesKey, timeInUs);
           // The data fields that are specified as the primary key columns cannot be left empty.
           row.addField("processor", ColumnValue.fromLong(i));
           row.addField("cpu_usage", ColumnValue.fromDouble(10.0));
           row.addField("cpu_sys", ColumnValue.fromDouble(5.0));
           rows.add(row);
       }
       String tableName = "<TIMESERIES_TABLE_NAME>";
       PutTimeseriesDataRequest putTimeseriesDataRequest = new PutTimeseriesDataRequest(tableName);
       putTimeseriesDataRequest.setRows(rows);
       client.putTimeseriesData(putTimeseriesDataRequest);
   }

   Dados resultantes na tabela após a escrita bem-sucedida:

   _m_name	_data_source	_tags	_time	processor	cpu_usage	cpu_sys
   cpu	host_0	["region=hangzhou"]	1712476524000000	0	10,0	5,0
   cpu	host_1	["region=hangzhou"]	1712476524000000	1	10,0	5,0
   cpu	host_2	["region=hangzhou"]	1712476524000000	2	10,0	5,0

3. Leia dados da tabela executando instruções SQL.

   1. Crie uma tabela de mapeamento SQL. Consulte Criar tabelas de mapeamento no modelo de múltiplos valores para tabelas de série temporal.

      Adicione os identificadores de série temporal e os campos personalizados (usados como chave primária) como chaves primárias na tabela de mapeamento SQL.

      Configuração de exemplo:

      CREATE TABLE `cpu::ts1` (
          `_m_name` VARCHAR(1024),
          `_data_source`  VARCHAR(1024),
          `_tags` VARCHAR(1024),
          `_time` BIGINT(20),
          `processor` BIGINT,
          `cpu_usage` DOUBLE,
          `cpu_sys` DOUBLE,
          PRIMARY KEY(`_m_name`,`_data_source`,`_tags`,`_time`,`processor`)
      );

   2. Execute a instrução SELECT para consultar dados. Consulte Consultar dados.

      Consulta de séries com cpu_usage superior a 90,0 via tabela de mapeamento cpu::ts1:

      SELECT `_m_name`, `_data_source`, `_tags` , `_time`, `processor` FROM `cpu::ts1` WHERE cpu_usage > 90.0;