Todos os produtos
Search
Central de documentação

MaxCompute:GET_JSON_OBJECT

Última atualização: Sep 18, 2026

A função GET_JSON_OBJECT extrai uma string de uma string JSON ou um valor do tipo de dados JSON com base em um caminho JSON especificado, json_path.

Sintaxe

STRING GET_JSON_OBJECT(JSON|STRING <json>, STRING <json_path>)

-- Example: Returns Alice.
SELECT GET_JSON_OBJECT(JSON '{"name": "Alice", "age": 30}', '$.name');

Notas de uso

  • A função GET_JSON_OBJECT não suporta sintaxe de expressão regular em caminhos JSON.

  • A sintaxe de caminho JSON do novo JSON data type difere da especificação original, o que pode causar problemas de compatibilidade.

  • Quando uma consulta contém múltiplas funções GET_JSON_OBJECT processando os mesmos dados JSON, a função analisa repetidamente a mesma string JSON, o que pode impactar negativamente o desempenho e aumentar os custos. Para evitar esse problema, use GET_JSON_OBJECT com uma função de tabela definida pelo usuário (UDTF) para transformar dados de log JSON.

Parâmetros

  • json: Obrigatório. Os dados JSON a processar. Este parâmetro suporta dois tipos de entrada: JSON e STRING.

    • Tipo JSON: Um valor do tipo de dados JSON. O valor deve estar no formato {"Key":"Value", "Key":"Value",...}, como JSON '{"name": "Alice", "age": 30}'.

    • Tipo STRING: Se a entrada for STRING, ela deve atender aos seguintes requisitos de formato:

      • A string deve estar no formato '{"Key":"Value", "Key":"Value",...}', como '{"name": "Alice", "age": 30}'.

      • Escape aspas duplas (") com duas barras invertidas (\\).

      • Escape aspas simples (') com uma barra invertida (\).

  • json_path: Obrigatório. Uma STRING que especifica a expressão de caminho JSON usada para extrair dados. O caminho deve iniciar com o caractere $, como $.aliyun.test[0].demo. A expressão de caminho utiliza os seguintes caracteres:

    • $: Indica o nó raiz.

    • . ou ['']: Indica um nó filho. Usado para analisar objetos JSON, como $.store.book. Se uma chave JSON contiver um ponto (.), use [''] como alternativa.

      A extração de dados com [''] só é suportada ao executar a instrução SET odps.sql.udf.getjsonobj.new=true;.

    • []: [number] indica um subscrito de array. O subscrito começa em 0.

    • *: Caractere curinga para []. Retorna o array inteiro. O asterisco (*) não pode ser escapado.

Valor de retorno

Retorna um valor do tipo STRING, correspondente aos dados extraídos do caminho especificado. A função segue estas regras para o valor de retorno:

  • Se json for válido e json_path existir, a função retorna a string correspondente.

  • Se json estiver vazio ou tiver um formato inválido, a função retorna NULL.

  • Se json_path contiver [*], o valor de retorno não estará em formato de array. Para forçar o valor de retorno a um formato de array unificado, execute a instrução SET odps.sql.force.getjsonobj.array.format=true;.

  • Se json_path for inválido, a função retorna NULL.

Comportamento de retorno

  • Controle o comportamento de retorno da função definindo o flag no nível do projeto ou da sessão com o seguinte comando: defina odps.sql.udf.getjsonobj.new=true/false;.

    Os dois comportamentos de retorno correspondentes às diferentes configurações do flag são os seguintes:

    Importante

    Recomendamos o uso da configuração SET odps.sql.udf.getjsonobj.new=true;. Essa configuração proporciona um comportamento de função mais padronizado, simplifica o processamento de dados e melhora o desempenho. Se o seu projeto MaxCompute possuir jobs existentes que dependem do comportamento de escape de caracteres reservados do JSON, recomendamos manter o comportamento original. Isso evita erros ou problemas de correção que poderiam ocorrer ao alternar para o novo comportamento sem verificação.

    Configurações de parâmetro

    SET odps.sql.udf.getjsonobj.new=true;

    SET odps.sql.udf.getjsonobj.new=false;

    Comportamento de retorno

    Retorna a string original sem modificação.

    Retorna a string com escape dos caracteres reservados do JSON.

    O valor de retorno é uma string JSON que pode ser analisada diretamente. Não é necessário usar funções como REPLACE ou REGEXP_REPLACE para substituir barras invertidas.

    Caracteres reservados do JSON, como quebras de linha (\n) e aspas ("), são retornados como as strings '\n' e '\"'.

    Análise de chaves duplicadas

    Um objeto JSON pode conter chaves duplicadas e a análise ocorre com sucesso.

    -- Returns 1.
    SELECT GET_JSON_OBJECT('{"a":"1","a":"2"}', '$.a');

    Um objeto JSON não pode conter chaves duplicadas. Se contiver, a análise pode falhar.

    -- Returns NULL.
    SELECT GET_JSON_OBJECT('{"a":"1","a":"2"}', '$.a');

    Ordem de classificação da saída

    A saída mantém a mesma ordem da string JSON original.

    -- Returns {"b":"1","a":"2"}.
    SELECT GET_JSON_OBJECT('{"b":{"b":"1","a":"2"},"a":"2"}', '$.b');

    A saída segue a ordem alfabética.

    -- Returns {"a":"2","b":"1"}.
    SELECT GET_JSON_OBJECT('{"b":{"b":"1","a":"2"},"a":"2"}', '$.b');
  • Quando o modo de compatibilidade com Hive está ativado por meio do comando SET odps.sql.hive.compatible=true;, a função GET_JSON_OBJECT preserva as strings originais no valor de retorno.

  • Para projetos MaxCompute criados em ou após 21 de janeiro de 2021, o comportamento de retorno padrão da função GET_JSON_OBJECT é preservar as strings originais.

  • Para projetos MaxCompute criados antes de 21 de janeiro de 2021, o comportamento de retorno padrão da função GET_JSON_OBJECT é aplicar escape nos caracteres reservados do JSON.

  • Use o exemplo a seguir para determinar qual comportamento a função GET_JSON_OBJECT utiliza no seu projeto MaxCompute. Execute o seguinte comando:

    SELECT GET_JSON_OBJECT('{"a":"[\\"1\\"]"}', '$.a');
    --The return value if the behavior is to escape JSON reserved characters:
    [\"1\"]
    
    --The return value if the behavior is to preserve original strings:
    ["1"]
    Para alterar o comportamento de retorno padrão da função GET_JSON_OBJECT no seu projeto para preservar strings originais, abra um ticket de suporte. Isso evita a necessidade de configurar a propriedade no nível da sessão a cada sessão.

Exemplos

JSON input parameter

Exemplo 1: Obter valores de chaves específicas em dados JSON

-- Returns 1.
SELECT GET_JSON_OBJECT(JSON '{"a":1, "b":2}', '$.a');

-- Returns NULL.
SELECT GET_JSON_OBJECT(JSON '{"a":1, "b":2}', '$.c');

Exemplo 2: Um json_path inválido retorna NULL.

-- Returns NULL.
SELECT GET_JSON_OBJECT(JSON '{"a":1, "b":2}', '$invalid_json_path');

STRING input parameter

Exemplo 1: Extrair informações do objeto JSON src_json.json

-- Prepare the test data.
CREATE TABLE IF NOT EXISTS src_json (
    json STRING
);

INSERT OVERWRITE TABLE src_json
VALUES
('{"store":
  {"fruit":[{"weight":8,"type":"apple"},
    {"weight":9,"type":"pear"}],
     "bicycle":{"price":19.95,
     "color":"red"}},
   "email":"amy@only_for_json_udf_test.net",
   "owner":"amy"}');

-- Extract the information of the owner field. The return value is amy.
SELECT GET_JSON_OBJECT(src_json.json, '$.owner') FROM src_json;

-- Optional. Output by preserving the original string.
SET odps.sql.udf.getjsonobj.new=true;
-- Extract the information of the first array in the store.fruit field. The return value is {"weight":8,"type":"apple"}.
SELECT GET_JSON_OBJECT(src_json.json, '$.store.fruit[0]') FROM src_json;

-- Extract the information of a non-existent field. The return value is NULL.
SELECT GET_JSON_OBJECT(src_json.json, '$.non_exist_key') FROM src_json;

Exemplo 2: Extrair informações de dados de array JSON

-- Returns 2222.
SELECT GET_JSON_OBJECT('{"array":[["aaaa",1111],["bbbb",2222],["cccc",3333]]}','$.array[1][1]');

-- Output by preserving the original string.
SET odps.sql.udf.getjsonobj.new=true;
-- Returns ["h0","h1","h2"].
SELECT GET_JSON_OBJECT('{"aaa":"bbb","ccc":{"ddd":"eee","fff":"ggg","hhh":["h0","h1","h2"]},"iii":"jjj"}','$.ccc.hhh[*]');

-- Output by escaping JSON reserved characters.
SET odps.sql.udf.getjsonobj.new=false;
-- Returns ["h0","h1","h2"].
SELECT GET_JSON_OBJECT('{"aaa":"bbb","ccc":{"ddd":"eee","fff":"ggg","hhh":["h0","h1","h2"]},"iii":"jjj"}','$.ccc.hhh[*]');

-- Returns h1.
SELECT GET_JSON_OBJECT('{"aaa":"bbb","ccc":{"ddd":"eee","fff":"ggg","hhh":["h0","h1","h2"]},"iii":"jjj"}','$.ccc.hhh[1]');

Exemplo 3: Extrair informações de dados JSON com ponto (.) na chave

-- Prepare the test data.
CREATE TABLE json_test (id STRING, json STRING);

-- Insert data where the key contains a period (.).
INSERT INTO TABLE json_test (id, json) VALUES 
("1", 
  "{
    \"China.beijing\":
      {\"school\":
        {\"id\":0,\"book\":
          [{\"title\": \"A\",\"price\": 8.95},
           {\"title\": \"B\",\"price\": 10.2}]
        }
      }
  }"
);

-- Insert data where the key does not contain a period (.).
INSERT INTO TABLE json_test (id, json) VALUES 
("2", 
  "{
    \"China_beijing\":
      {\"school\":
        {\"id\":0,\"book\":
          [{\"title\": \"A\",\"price\": 8.95},
           {\"title\": \"B\",\"price\": 10.2}]
        }
      }
  }"
);

-- Use square brackets [''] to parse data that contains a period (.).
-- This extracts the 'id' value under 'China.beijing'. The return value is 0.
SELECT GET_JSON_OBJECT(json, "$['China.beijing'].school['id']") FROM json_test WHERE id =1;

-- For data without special characters, both '.' and [''] are valid and equivalent.
-- This extracts the 'id' value under 'China_beijing'. The return value is 0.
SELECT GET_JSON_OBJECT(json, "$['China_beijing'].school['id']") FROM json_test WHERE id =2;
SELECT GET_JSON_OBJECT(json, "$.China_beijing.school['id']") FROM json_test WHERE id =2;

Exemplo 4: Usar [''] para chaves que contêm ponto (.)

SET odps.sql.udf.getjsonobj.new=true;

-- Returns 1.
SELECT GET_JSON_OBJECT('{"a.1":"1","a":"2"}', '$[\'a.1\']');

Exemplo 5: Entrada JSON vazia ou inválida

-- Returns NULL.
SELECT GET_JSON_OBJECT('','$.array[1][1]');

-- Returns NULL.
SELECT GET_JSON_OBJECT('"array":["aaaa",1111],"bbbb":["cccc",3333]','$.array[1][1]');

Exemplo 6: Strings JSON com escape

SET odps.sql.udf.getjsonobj.new=true;

--Returns "1".
SELECT GET_JSON_OBJECT('{"a":"\\"1\\"","b":"2"}', '$.a'); 

--Returns '1'.
SELECT GET_JSON_OBJECT('{"a":"\'1\'","b":"2"}', '$.a');

Exemplo 7: Suporte a emojis

-- Returns the emoji symbol.
SELECT GET_JSON_OBJECT('{"a":"<Emoji symbol>"}', '$.a');
Observação: o DataWorks não suporta a inserção direta de caracteres emoji. Utilize uma ferramenta como o Data Integration para gravar as strings codificadas correspondentes aos caracteres emoji no MaxCompute. Em seguida, use a função GET_JSON_OBJECT para processá-las.

Funções relacionadas