SelectObject - Interroger des objets CSV et JSON avec SQL - Object Storage Service

Exécute des instructions SQL sur un objet cible et renvoie les résultats.

Notes d'utilisation

Vous devez disposer des autorisations de lecture sur l'objet.
Une instruction SQL valide renvoie le code d'état HTTP 206. Une instruction SQL invalide ou ne correspondant pas aux données renvoie le code d'état HTTP 400.
Lorsque vous utilisez l'API SelectObject pour interroger des données, la facturation est basée sur le volume réel de données analysées à partir de l'objet source. Pour plus d'informations, consultez la section Frais de traitement des données.

Syntaxe de la requête

La syntaxe de la requête diffère selon que l'objet est au format CSV ou JSON.

Syntaxe de la requête pour les objets CSV

POST /object?x-oss-process=csv/select HTTP/1.1 
HOST: BucketName.oss-cn-hangzhou.aliyuncs.com 
Date: time GMT
Content-Length: ContentLength
Content-MD5: MD5Value 
Authorization: Signature
<?xml  version="1.0"  encoding="UTF-8"?>
<SelectRequest>    
    <Expression>Base64-encoded SQL statement. Example: c2VsZWN0IGNvdW50KCopIGZyb20gb3Nzb2JqZWN0IHdoZXJlIF80ID4gNDU=</Expression>
    <InputSerialization>
        <CompressionType>None|GZIP</CompressionType>
        <CSV>            
            <FileHeaderInfo>
                NONE|IGNORE|USE
            </FileHeaderInfo>
            <RecordDelimiter>Base64-encoded character</RecordDelimiter>
            <FieldDelimiter>Base64-encoded character</FieldDelimiter>
            <QuoteCharacter>Base64-encoded character</QuoteCharacter>
            <CommentCharacter>Base64-encoded character</CommentCharacter>
            <Range>line-range=start-end|split-range=start-end</Range>
            <AllowQuotedRecordDelimiter>true|false</AllowQuotedRecordDelimiter>
        </CSV>   
        </InputSerialization>
        <OutputSerialization>
             <CSV>
             <RecordDelimiter>Base64-encoded character</RecordDelimiter>
             <FieldDelimiter>Base64-encoded character</FieldDelimiter>

            </CSV>
            <KeepAllColumns>false|true</KeepAllColumns>
            <OutputRawData>false|true</OutputRawData>
            <EnablePayloadCrc>true</EnablePayloadCrc>
            <OutputHeader>false</OutputHeader>
       </OutputSerialization>
     <Options>
        <SkipPartialDataRecord>false</SkipPartialDataRecord>
        <MaxSkippedRecordsAllowed>
        max allowed number of records skipped
        </MaxSkippedRecordsAllowed>
    </Options>
</SelectRequest>

Syntaxe de la requête pour les objets JSON

POST /object?x-oss-process=json/select HTTP/1.1 
HOST: BucketName.oss-cn-hangzhou.aliyuncs.com 
Date: time GMT
Content-Length: ContentLength
Content-MD5: MD5Value 
Authorization: Signature
<?xml  version="1.0"  encoding="UTF-8"?>
<SelectRequest>    
    <Expression>
        Base64-encoded SQL statement. Example: c2VsZWN0IGNvdW50KCopIGZyb20gb3Nzb2JqZWN0IHdoZXJlIF80ID4gNDU=
    </Expression>
    <InputSerialization>
        <CompressionType>None|GZIP</CompressionType>
        <JSON>
            <Type>DOCUMENT|LINES</Type>
            <Range>
            line-range=start-end|split-range=start-end
            </Range>
            <ParseJsonNumberAsString> true|false
            </ParseJsonNumberAsString>
        </JSON>
    </InputSerialization>
    <OutputSerialization>
        <JSON>
            <RecordDelimiter>
                Base64 of record delimiter
            </RecordDelimiter>
        </JSON>
        <OutputRawData>false|true</OutputRawData>
                 <EnablePayloadCrc>true</EnablePayloadCrc>
    </OutputSerialization>
    <Options>
        <SkipPartialDataRecord>
            false|true
        </SkipPartialDataRecord>
        <MaxSkippedRecordsAllowed>
            max allowed number of records skipped
           </MaxSkippedRecordsAllowed>
        </Options>
</SelectRequest>

Éléments de la requête

Élément	Type	Description
SelectRequest	Conteneur	Conteneur qui stocke la requête SelectObject. Nœuds enfants : Expression, InputSerialization et OutputSerialization Nœuds parents : aucun
Expression	Chaîne	Instruction SQL encodée en Base64. Nœuds enfants : aucun Nœud parent : SelectRequest
InputSerialization	Conteneur	Facultatif. Spécifie les paramètres de sérialisation d'entrée. Nœuds enfants : CompressionType, CSV et JSON Nœud parent : SelectRequest
OutputSerialization	Conteneur	Facultatif. Spécifie les paramètres de sérialisation de sortie. Nœuds enfants : CSV, JSON et OutputRawData Nœud parent : SelectRequest
CSV(InputSerialization)	Conteneur	Facultatif. Spécifie les paramètres de sérialisation d'entrée pour les objets CSV. Nœuds enfants : FileHeaderInfo, RecordDelimiter, FieldDelimiter, QuoteCharacter, CommentCharacter et Range Nœud parent : InputSerialization
CSV(OutputSerialization)	Conteneur	Facultatif. Spécifie les paramètres de sérialisation de sortie pour les objets CSV. Nœuds enfants : RecordDelimiter et FieldDelimiter Nœud parent : OutputSerialization
JSON(InputSerialization)	Conteneur	Facultatif. Spécifie les paramètres de sérialisation d'entrée pour les objets JSON. Nœuds enfants : Type, Range et ParseJsonNumberAsString
JSON(OutputSerialization)	Conteneur	Facultatif. Spécifie les paramètres de sérialisation de sortie pour les objets JSON. Nœuds enfants : RecordDelimiter
Type	Énumération	Type de l'objet JSON d'entrée. Valeurs valides : DOCUMENT et LINES.
OutputRawData	Booléen	Facultatif. Indique s'il faut exporter les données brutes. Valeur par défaut : false. Nœuds enfants : aucun Nœud parent : OutputSerialization Remarque Si vous spécifiez OutputRawData dans la requête, Object Storage Service (OSS) renvoie les données en fonction de l'élément de la requête. Si vous ne spécifiez pas OutputRawData dans la requête, OSS sélectionne automatiquement un format et renvoie les données dans ce format dans la réponse. Si vous définissez OutputRawData sur true et que l'instruction SQL envoyée met beaucoup de temps à renvoyer des données, la requête HTTP peut expirer.
CompressionType	Énumération	Type de compression de l'objet. Valeurs valides : None et GZIP. Nœuds enfants : aucun Nœud parent : InputSerialization
FileHeaderInfo	Énumération	Facultatif. Spécifie les informations d'en-tête du fichier CSV. Valeurs valides : Use : l'objet CSV contient des informations d'en-tête. Vous pouvez utiliser les noms de colonnes de l'objet CSV comme noms de colonnes dans l'opération SelectObject. Ignore : l'objet CSV contient des informations d'en-tête. Les noms de colonnes de l'objet CSV ne peuvent pas être utilisés comme noms de colonnes dans l'opération SelectObject. None : l'objet CSV ne contient pas d'informations d'en-tête. Il s'agit de la valeur par défaut. Nœuds enfants : aucun Nœud parent : CSV (entrée)
RecordDelimiter	Chaîne	Facultatif. Spécifie un saut de ligne encodé en Base64. Valeur par défaut : `\n`. Avant l'encodage de la valeur de cet élément, celle-ci doit être une valeur ANSI d'une longueur maximale de deux caractères. Par exemple, `\n` est utilisé pour indiquer un saut de ligne en Java. Nœuds enfants : aucun Nœuds parents : CSV (entrée et sortie) et JSON (sortie)
FieldDelimiter	Chaîne	Facultatif. Spécifie le délimiteur de colonne encodé en Base64 pour l'objet CSV. Valeur par défaut : `,`. Avant l'encodage de la valeur de cet élément, celle-ci doit être une valeur ANSI d'un seul caractère. Par exemple, `,` est utilisé pour indiquer une virgule en Java. Nœuds enfants : aucun Nœuds parents : CSV (entrée et sortie)
QuoteCharacter	Chaîne	Facultatif. Spécifie un caractère de guillemet encodé en Base64 pour l'objet CSV. Valeur par défaut : `\"`. Dans un objet CSV, les sauts de ligne et les délimiteurs de colonne entourés de guillemets sont traités comme des caractères normaux. Avant l'encodage de la valeur de cet élément, celle-ci doit être une valeur ANSI d'un seul caractère. Par exemple, `\"` est utilisé pour indiquer un guillemet en Java. Nœuds enfants : aucun Nœud parent : CSV (entrée)
CommentCharacter	Chaîne	Caractère de commentaire à utiliser dans l'objet CSV. La valeur de cet élément doit être encodée en Base64. Cet élément est vide par défaut.
Range	Chaîne	Facultatif. Spécifie la plage de la requête. Méthodes prises en charge : Remarque SelectMeta doit être créé pour les objets interrogés en fonction de la plage (Range). Requête par ligne : line-range=début-fin. Par exemple, line-range=10-20 indique que les données de la ligne 10 à la ligne 20 sont analysées. Requête par fragment : split-range=début-fin. Par exemple, split-range=10-20 indique que les données du fragment 10 au fragment 20 sont analysées. Les paramètres de début et de fin sont inclusifs. Ces deux paramètres utilisent le même format que le paramètre range dans une requête de plage (range get). Ce paramètre ne peut être utilisé que si l'objet est au format CSV ou si le type JSON est LINES. Nœuds enfants : aucun Nœuds parents : CSV (entrée) et JSON (sortie)
KeepAllColumns	bool	Facultatif. Indique si toutes les colonnes de l'objet CSV sont incluses dans la réponse. Valeur par défaut : false. Seules les colonnes de la clause SELECT contiennent des valeurs. Les colonnes de la réponse sont triées par numéro de colonne dans l'ordre croissant. Exemple : `select _5, _1 from ossobject.` Si vous définissez KeepAllColumns sur true et que l'objet CSV comprend six colonnes, le résultat suivant est renvoyé pour la clause SELECT précédente : Valeur de la 1re colonne,,,,Valeur de la 5e colonne,\n Nœuds enfants : aucun Nœud parent : OutputSerialization (CSV)
EnablePayloadCrc	bool	Valeur CRC-32 pour la vérification de chaque trame. Le client peut calculer la valeur CRC-32 de chaque charge utile et la comparer à la valeur CRC-32 incluse pour vérifier l'intégrité des données. Nœuds enfants : aucun Nœud parent : OutputSerialization
Options	Conteneur	Autres paramètres facultatifs. Nœuds enfants : SkipPartialDataRecord et MaxSkippedRecordsAllowed Nœud parent : SelectRequest
OutputHeader	bool	Indique si les informations d'en-tête de l'objet CSV sont incluses au début de la réponse. Valeur par défaut : false. Nœuds enfants : aucun Nœud parent : OutputSerialization
SkipPartialDataRecord	bool	Indique s'il faut ignorer les lignes contenant des données manquantes. Si ce paramètre est défini sur false, OSS traite les données de la ligne comme nulles sans signaler d'erreur. Si ce paramètre est défini sur true, les lignes ne contenant pas de données sont ignorées. Si le nombre de lignes ignorées dépasse le nombre maximal de lignes pouvant être ignorées, OSS signale une erreur et arrête le traitement des données. Valeur par défaut : false. Nœuds enfants : aucun Nœud parent : Options
MaxSkippedRecordsAllowed	Int	Nombre maximal de lignes pouvant être ignorées. Si une ligne ne correspond pas au type spécifié dans l'instruction SQL, ou si une ou plusieurs colonnes d'une ligne sont manquantes et que la valeur de SkipPartialDataRecord est true, les lignes sont ignorées. Si le nombre de lignes ignorées dépasse la valeur de ce paramètre, OSS signale une erreur et arrête le traitement des données. Remarque Si une ligne d'un objet CSV n'est pas correctement formatée, OSS arrête le traitement des données et signale une erreur, car cette erreur de formatage peut entraîner une analyse incorrecte de l'objet CSV. Par exemple, une colonne de la ligne contient un nombre impair continu de caractères de guillemet. Ce paramètre permet de modifier la tolérance aux données irrégulières, mais ne peut pas être configuré pour des objets CSV non valides. Valeur par défaut : 0. Nœuds enfants : aucun Nœud parent : Options
ParseJsonNumberAsString	bool	Indique s'il faut analyser les entiers et les nombres à virgule flottante de l'objet JSON sous forme de chaînes. La précision des nombres à virgule flottante diminue lors de l'analyse. Pour conserver les données brutes, définissez ce paramètre sur true. Utilisez la fonction CAST en SQL pour convertir les données analysées vers le type requis, tel que INT, DOUBLE ou DECIMAL. Valeur par défaut : false. Nœuds enfants : aucun Nœud parent : JSON
AllowQuotedRecordDelimiter	bool	Indique si l'objet CSV peut contenir des sauts de ligne entre guillemets ("). Par exemple, si la valeur d'une colonne est "abc\ndef" et que \n est un saut de ligne, définissez ce paramètre sur true. Si ce paramètre est défini sur false, vous pouvez appeler l'opération SelectObject pour spécifier une plage dans l'en-tête de la requête afin d'effectuer des requêtes multipartites plus efficaces. Valeur par défaut : true. Nœuds enfants : aucun Nœud parent : InputSerialization

Corps de la réponse

Si la réponse renvoie le code d'état HTTP 4xx, la vérification de la syntaxe SQL a échoué ou la requête contient des erreurs. Le format du corps d'erreur est identique à celui des erreurs GetObject.
Si la réponse renvoie le code d'état HTTP 5xx, une erreur interne du serveur s'est produite. Le format du corps d'erreur est identique à celui des erreurs GetObject.
Le code d'état HTTP 206 indique un succès.
- Si la valeur de l'en-tête x-oss-select-output-raw est true, les données de l'objet, à l'exception des données basées sur des trames, sont renvoyées. Le client peut obtenir les données de la même manière que lors de l'opération GetObject.
- Si la valeur de x-oss-select-output-raw est false, le résultat est renvoyé sous forme de trames.
Les trames sont renvoyées au format Version|Frame-Type | Payload Length | Header Checksum | Payload | Payload Checksum<1 byte><--3 bytes--><---4 bytes----><-------4 bytes--><variable><----4bytes---------->.

Remarque
La valeur de Checksum dans les trames est CRC-32. Tous les entiers d'une trame sont en ordre big-endian. Actuellement, la valeur de Version est 1.

Types de trame

SelectObject prend en charge trois types de trames.

Type de trame	Valeur	Format de la charge utile	Description
Data Frame	8388609	offset \| data<-8 bytes><---variable->	Données renvoyées pour la requête SelectObject. La valeur du paramètre offset est un entier de 8 bits qui indique l'emplacement d'analyse actuel (le décalage par rapport à l'en-tête du fichier). Ce paramètre sert à signaler la progression de l'opération.
Continuous Frame	8388612	offset<----8 bytes-->	Trame utilisée pour signaler la progression d'une opération et maintenir une connexion HTTP. Si aucune donnée n'est renvoyée pour une requête dans un délai de 5 secondes, une trame continue est retournée.
End Frame	8388613	offset \| total scanned bytes \| http status code \| error message<--8bytes-><--8bytes---------><----4 bytes--------><-variable------>	Une trame de fin permet de renvoyer l'état final d'une opération, y compris le nombre d'octets analysés et les éventuels messages d'erreur. Le paramètre offset indique le décalage d'emplacement final une fois l'analyse terminée. Le paramètre total scanned bytes indique la taille des données analysées. Le paramètre http status code indique l'état final de l'opération. Remarque SelectObject est une opération en flux continu. Seul le premier bloc de données est traité lors de l'envoi de l'en-tête de réponse. Si le premier bloc de données correspond à l'instruction SQL, le code d'état HTTP dans l'en-tête de réponse est 206. Ce code indique que l'opération a réussi. Toutefois, le code d'état final peut ne pas être 206, car les blocs de données suivants peuvent être invalides. Le code d'état dans l'en-tête de réponse ne peut pas être modifié. Un code d'état HTTP est inclus dans la trame de fin pour indiquer l'état final de l'opération. Le client utilise le code d'état inclus dans la trame de fin pour déterminer si l'opération a réussi. Le paramètre error message indique les messages d'erreur, y compris le numéro de chaque ligne ignorée et le nombre total de lignes ignorées. Remarque Le format des messages d'erreur inclus dans une trame de fin est `ErrorCodes.DetailMessage`. La section ErrorCodes contient un ou plusieurs codes d'erreur séparés par des virgules (,). ErrorCodes et DetailMessage sont séparés par un point (.).

Exemples de requêtes

Exemples pour les objets CSV et JSON :

Exemples de requêtes pour les objets CSV

POST /oss-select/bigcsv_normal.csv?x-oss-process=csv%2Fselect HTTP/1.1
Date: Fri, 25 May 2018 22:11:39 GMT
Content-Type:
Authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
User-Agent: aliyun-sdk-dotnet/2.8.0.0(windows 16.7/16.7.0.0/x86;4.0.30319.42000)
Content-Length: 748
Expect: 100-continue
Connection: keep-alive
Host: host name
<?xml version="1.0"?>
<SelectRequest>
    <Expression>c2VsZWN0IGNvdW50KCopIGZyb20gb3Nzb2JqZWN0IHdoZXJlIF80ID4gNDU=
    </Expression>
    <InputSerialization>
        <Compression>None</Compression>
        <CSV>
            <FileHeaderInfo>Ignore</FileHeaderInfo>
            <RecordDelimiter>Cg==</RecordDelimiter>
            <FieldDelimiter>LA==</FieldDelimiter>
            <QuoteCharacter>Ig==</QuoteCharacter>
            <CommentCharacter>Iw==</CommentCharacter/>
        </CSV>
    </InputSerialization>
    <OutputSerialization>
        <CSV>
            <RecordDelimiter>Cg==</RecordDelimiter>
            <FieldDelimiter>LA==</FieldDelimiter>
            <QuoteCharacter>Ig==</QuoteCharacter>            
        </CSV>
        <KeepAllColumns>false</KeepAllColumns>
            <OutputRawData>false</OutputRawData>
    </OutputSerialization>
</SelectRequest>

Exemples de requêtes pour les objets JSON

POST /oss-select/sample_json.json?x-oss-process=json%2Fselect HTTP/1.1
Host: host name
Accept-Encoding: identity
User-Agent: aliyun-sdk-python/2.6.0(Darwin/16.7.0/x86_64;3.5.4)
Accept: */*
Connection: keep-alive
date: Mon, 10 Dec 2018 18:28:11 GMT
authorization: OSS4-HMAC-SHA256 Credential=LTAI********************/20250417/cn-hangzhou/oss/aliyun_v4_request,AdditionalHeaders=content-length,Signature=a7c3554c729d71929e0b84489addee6b2e8d5cb48595adfc51868c299c0c218e
Content-Length: 317
<SelectRequest>
    <Expression>c2VsZWN0ICogZnJvbSBvc3NvYmplY3Qub2JqZWN0c1sqXSB3aGVyZSBwYXJ0eSA9ICdEZW1vY3JhdCc=
    </Expression>
    <InputSerialization>
    <JSON>
        <Type>DOCUMENT</Type>
    </JSON>
    </InputSerialization>
    <OutputSerialization>
    <JSON>
        <RecordDelimiter>LA==</RecordDelimiter>
    </JSON>
    </OutputSerialization>
    <Options />
</SelectRequest>

Syntaxe des instructions SQL

La forme générale d'une instruction SQL SelectObject est SELECT select-list from table where_opt limit_opt.

Important

Les mots-clés suivants ne peuvent pas être modifiés : SELECT et where.

select_list: column name
            | column index (Example: _1, _2. column index applies only to CSV objects.)
            | json path (Example: s.contacts.firstname. json path applies only to JSON objects.)
            | function(column index | column name)
            | function(json_path) (applies only to JSON objects.)
            | select_list AS alias

Remarque

Les fonctions suivantes sont prises en charge : AVG, SUM, MAX, MIN, COUNT et CAST (fonction de conversion de type). Vous ne pouvez spécifier qu'un astérisque (*) après COUNT.

table: OSSOBJECT

      | OSSOBJECT json_path (applies only to JSON objects.)

If you want to perform operations on CSV objects, you must use the OSSOBJECT table. If you want to perform operations on JSON objects including DOCUMENT and LINES type objects, you can specify json_path after OSSOBJECT. 

json_path: ['string '] (The quotation marks that are used to enclose a string can be deleted if the string does not include a space or an asterisk (*). In this case, ['string '] is equivalent to .'string '.)

          | [n] (indicates the nth element in an array. The value of n is counted from 0.)

          | [*] (indicates a child element in an array or object.)

          | .'string ' (The quotation marks that are used to enclose a string can be deleted if the string does not include a space or an asterisk (*).)

          | json_path jsonpath (You can concatenate multiple elements in a json path such as [n].property1.attributes[*].)

Where_opt:
| WHERE expr
expr:
| literal value
| column name
| column index
| json path (applies only to JSON objects.)
| expr op expr
| expr OR expr
| expr AND expr
| expr IS NULL
| expr IS NOT NULL
| (column name | column index | json path) IN (value1, value2, ...)
| (column name | column index | json path) NOT in (value1, value2, ...)
| (column name | column index | json path) between value1 and value2
| NOT (expr)
| expr op expr
| (expr)
| cast (column index |column name | json path | literal as INT|DOUBLE|)

op : inclut les opérateurs suivants : >, <, >=, <=, ! =, =, ,, LIKE, +, -, *, /, %, et ||.
cast : vous pouvez utiliser la fonction CAST pour convertir les données d'une colonne d'un type vers un autre.
Combinaison d'une fonction d'agrégation et de limit : Select avg(cast(_1 as int)) from ossobject limit 100. L'instruction précédente calcule la valeur moyenne de la première colonne sur les 100 premières lignes. Cette fonction diffère de l'instruction prise en charge par MySQL, car une seule ligne est renvoyée pour une fonction d'agrégation dans les opérations SelectObject. Par conséquent, aucune limite n'est configurée pour la taille des données de sortie. L'opération limit est effectuée avant l'opération d'agrégation lorsque vous appelez SelectObject.

Limites des instructions SQL

Les instructions SQL présentent les limites suivantes :

Seuls les objets texte encodés en UTF-8 et les objets texte UTF-8 compressés au format GZIP sont pris en charge. Le format deflate n'est pas pris en charge pour les objets GZIP.
Un seul objet peut être interrogé lors de l'utilisation d'une instruction SQL. Les clauses suivantes ne sont pas prises en charge : JOIN, ORDER BY, GROUP BY et HAVING.
Une clause WHERE ne peut pas inclure de conditions d'agrégation. Par exemple, la clause suivante n'est pas autorisée : WHERE max(cast(age as int)) > 100.
Un maximum de 1 000 colonnes peut être spécifié pour une instruction SQL. Le nom de colonne dans une instruction SQL peut comporter jusqu'à 1 024 octets.
Un maximum de cinq caractères génériques (%) est pris en charge dans une clause LIKE. Le signe pourcentage (%) et l'astérisque () sont des caractères génériques qui indiquent zéro ou plusieurs caractères. Le mot-clé ESCAPE est pris en charge pour les clauses SQL LIKE et permet de convertir des caractères spéciaux tels que les signes pourcentage (%), les astérisques () et les points d'interrogation (?) en chaînes normales.
Un maximum de 1 024 constantes est pris en charge dans une clause IN.
La projection spécifiée après SELECT peut être un nom de colonne, un index de colonne CSV (tel que _1 ou _2), une fonction d'agrégation ou une fonction CAST. D'autres expressions ne sont pas prises en charge, telles que select _1 + _2 from ossobject.
La taille maximale de colonne et de ligne pour un objet CSV est de 256 Ko.
Les chemins JSON spécifiés après FROM prennent en charge les nœuds JSON dont la taille maximale est de 512 Ko. Le chemin peut contenir jusqu'à 10 niveaux et un tableau peut contenir jusqu'à 5 000 éléments. Les champs spécifiés après SELECT et WHERE doivent provenir des nœuds correspondant aux chemins JSON spécifiés après FROM.
Dans les instructions SQL d'un objet JSON, les expressions SELECT ou WHERE ne peuvent pas inclure de caractères génériques de tableau ([]). Les caractères génériques de tableau ([]) ne peuvent être inclus que dans les chemins JSON spécifiés après FROM. Par exemple, vous pouvez utiliser select from ossobject.contacts[] au lieu de select s.contacts[*] from ossobject s.
La taille maximale d'une instruction SQL est de 16 Ko. Jusqu'à 20 expressions peuvent être ajoutées après WHERE. Chaque instruction prend en charge jusqu'à 10 niveaux et 100 opérations d'agrégation.

Gestion des erreurs de données

Les scénarios suivants décrivent la gestion des erreurs de données.

Certaines colonnes sont manquantes dans certaines lignes d'un objet CSV.

Si SkipPartialDataRecord n'est pas spécifié ou est défini sur false, OSS calcule les expressions de l'instruction SQL en traitant les valeurs des colonnes manquantes comme null.

Si SkipPartialDataRecord est défini sur true, OSS ignore les lignes dans lesquelles certaines colonnes sont manquantes. Dans ce cas, si MaxSkippedRecordsAllowed n'est pas spécifié ou est défini sur une valeur inférieure au nombre de lignes ignorées, OSS signale une erreur en envoyant le code d'état HTTP 400 ou en incluant le code d'état HTTP 400 dans la trame de fin.

Supposons que l'instruction SQL select _1, _3 from ossobject soit exécutée et que les données d'une ligne de l'objet CSV soient « John, Company A ».
- Si SkipPartialDataRecord est défini sur false, « John,\n » est renvoyé.
- Si SkipPartialDataRecord est défini sur true, cette ligne est ignorée.
Certaines clés sont manquantes dans un objet JSON.

Certains objets JSON peuvent exclure les clés spécifiées dans l'instruction SQL.
- Si SkipPartialDataRecord n'est pas spécifié ou est défini sur false, OSS calcule les expressions de l'instruction SQL en traitant les clés manquantes comme null.
- Si SkipPartialDataRecord est défini sur true, OSS ignore les données du nœud JSON. Dans ce cas, si MaxSkippedRecordsAllowed n'est pas spécifié ou est défini sur une valeur inférieure au nombre de lignes ignorées, OSS signale une erreur en envoyant le code d'état HTTP 400 ou en incluant le code d'état HTTP 400 dans la trame de fin.
Supposons que l'instruction SQL select s.firstName, s.lastName , s.age from ossobject.contacts[*] s soit exécutée et que la valeur d'un nœud JSON soit {"firstName":"John", "lastName":"Smith"}.
- Si SkipPartialDataRecord n'est pas spécifié ou est défini sur false, {"firstName":"John", "lastName":"Smith"} est renvoyé.
- Si SkipPartialDataRecord est défini sur true, cette ligne est ignorée.
Remarque
Pour les clés dans les données renvoyées d'une requête pour des objets JSON, les objets JSON de sortie ne peuvent être que de type LINES. La valeur Key dans la sortie est renvoyée selon les règles suivantes :
- Supposons que l'instruction SQL select * from ossobject… soit exécutée. Si correspond à un objet JSON ({...}), l'objet JSON est renvoyé. Si correspond à une chaîne ou à un tableau, la chaîne ou le tableau est renvoyé en tant que DummyKey _1.
  
  Si {"Age":5}select * from ossobject.Age s where s = 5 est utilisé, {"_1":5} est renvoyé car la valeur 5 correspondant à * n'est pas un objet JSON. Lorsque l'instruction SQL select * from ossobject s where s.Age = 5 est exécutée, {"Age":5} correspondant à * est renvoyé.
- Si l'instruction SQL n'utilise pas select * mais spécifie des colonnes, le contenu renvoyé est au format {"{Column 1}": Value, "{Column 2}": Value...}. {Column n} peut être généré à l'aide des méthodes suivantes :
  - Si l'alias de la colonne est spécifié dans la clause SELECT, l'alias prend effet.
  - Si le nom de la colonne est la clé d'un objet JSON, cette clé est utilisée comme valeur de clé de sortie.
  - Si la colonne est un élément d'un tableau JSON ou une fonction d'agrégation, préfixez le nom de la colonne avec le numéro de série (à partir de 1) et un trait de soulignement (_) comme valeur de clé de sortie.
  Supposons que {"contacts":{"Age":35, "Children":["child1", "child2", "child3"]}} soit utilisé :
  
  Lorsque l'instruction SQL select s.contacts.Age, s.contacts.Children[0] from ossobjects est exécutée, Age est la clé de l'objet JSON d'entrée et Children[0] indique le premier élément du tableau Children et constitue la deuxième colonne du contenu de sortie. Dans ce cas, {"Age":35, "_2":"child1"} est renvoyé.
  
  Lorsque l'instruction SQL select max(cast(s.Age as int)) from ossobject.contacts s est exécutée et que la colonne sélectionnée est une fonction d'agrégation, la colonne est préfixée par _1 et son numéro de série dans la sortie. Dans ce cas, {"_1":35} est renvoyé.
  
  Lorsque l'alias de la colonne est spécifié dans l'instruction SQL select s.contacts.Age, s.contacts.Children[0] as firstChild from ossobject, {"Age":35, "firstChild":"child1"} est renvoyé.
- Les clés qui correspondent aux objets JSON et aux instructions SQL sont sensibles à la casse. Par exemple, « select s. Age » et « select s. age » sont différents.
Le type de données de certaines colonnes dans un objet CSV ne correspond pas au type de données spécifié dans l'instruction SQL.

Si le type de données d'une ligne dans un objet CSV ne correspond pas au type spécifié dans l'instruction SQL, la ligne est ignorée. Si le nombre de lignes ignorées dépasse la valeur de MaxSkippedRecordsAllowed, OSS arrête le traitement des données et renvoie le code d'état HTTP 400.

Supposons que l'instruction SQL select _1, _3 from ossobject where _3 > 5 soit exécutée. Si la valeur d'une ligne dans l'objet CSV est John, Company A, To be hired, cette ligne est ignorée car la troisième colonne de la ligne n'est pas de type entier.
Le type de données de certaines clés dans un objet JSON ne correspond pas au type de données spécifié dans l'instruction SQL.

Supposons que l'instruction SQL select s.name from ossobject s where s.aliren_age > 5 soit exécutée. Si la valeur d'un nœud JSON est {"Name":"John", "Career_age": To be hired}, ce nœud est ignoré.

Formats de date et d'heure pris en charge

Le tableau suivant répertorie les formats qui peuvent être convertis en horodatage sans qu'il soit nécessaire de spécifier le format de date et d'heure. Par exemple, la chaîne cast('20121201' as timestamp) est automatiquement analysée comme un horodatage du 1er décembre 2012.

Format

Description

YYYYMMDD

année mois jour

YYYY/MM/DD

année/mois/jour

DD/MM/YYYY/

jour/mois/année

YYYY-MM-DD

année-mois-jour

DD-MM-YY

jour-mois-année

DD.MM.YY

jour. mois. année

HH:MM:SS.mss

heure:minute:seconde. milliseconde

HH:MM:SS

heure:minute:seconde

HH MM SS mss

heure minute seconde milliseconde

HH.MM.SS.mss

heure. minute. seconde. milliseconde

HHMM

heure minute

HHMMSSmss

heure minute seconde milliseconde

YYYYMMDD HH:MM:SS.mss

année mois jour heure:minute:seconde. milliseconde

YYYY/MM/DD HH:MM:SS.mss

année/mois/jour heure:minute:seconde. milliseconde

DD/MM/YYYY HH:MM:SS.mss

jour/mois/année heure:minute:seconde. milliseconde

YYYYMMDD HH:MM:SS

année mois jour heure:minute:seconde

YYYY/MM/DD HH:MM:SS

année/mois/jour heure:minute:seconde

DD/MM/YYYY HH:MM:SS

jour/mois/année heure:minute:seconde

YYYY-MM-DD HH:MM:SS.mss

année-mois-jour heure:minute:seconde. milliseconde

DD-MM-YYYY HH:MM:SS.mss

jour-mois-année heure:minute:seconde. milliseconde

YYYY-MM-DD HH:MM:SS

année-mois-jour heure:minute:seconde

YYYYMMDDTHH:MM:SS

année mois jour T heure:minute:seconde

YYYYMMDDTHH:MM:SS.mss

année mois jour T heure:minute:seconde. milliseconde

DD-MM-YYYYTHH:MM:SS.mss

jour-mois-année T heure:minute:seconde. milliseconde

DD-MM-YYYYTHH:MM:SS

jour-mois-année T heure:minute:seconde

YYYYMMDDTHHMM

année mois jour T heure minute

YYYYMMDDTHHMMSS

année mois jour T heure minute seconde

YYYYMMDDTHHMMSSMSS

année mois jour T heure minute seconde milliseconde

ISO8601-0

année-mois-jour T heure:minute+heure:minute, ou année-mois-jour T heure: minute-heure:minute

« + » indique que l'heure locale dans le fuseau horaire actuel est postérieure à l'heure UTC standard. « - » indique que l'heure locale dans le fuseau horaire actuel est antérieure à l'heure UTC standard. Dans ce format, ISO8601-0 peut être utilisé.

ISO8601-1

année-mois-jour T heure:minute+heure:minute, ou année-mois-jour T heure: minute-heure:minute

CommonLog

Exemple : 28/Feb/2017:12:30:51 +0700

RFC822

Exemple : Tue, 28 Feb 2017 12:30:51 GMT

?D/?M/YY

jour/mois/année, où le jour et le mois peuvent comporter un ou deux chiffres.

?D/?M/YY ?H:?M

jour/mois/année/heure:minute, où le jour, le mois, l'heure et la minute peuvent comporter un ou deux chiffres.

?D/?M/YY ?H:?M:?S

jour/mois/année/heure:minute:seconde, où le jour, le mois, l'heure, la minute et la seconde peuvent comporter un ou deux chiffres.

Le tableau suivant répertorie les formats susceptibles de provoquer des erreurs. Vous devez spécifier un format de date et d'heure lorsque vous utilisez des chaînes dans ces formats. Par exemple, l'instruction cast('20121201' as timestamp format 'YYYYDDMM') analyse incorrectement la chaîne 20121201 comme étant le 12 janvier 2012.

Format

Description

YYYYDDMM

année jour mois

YYYY/DD/MM

année/jour/mois

MM/DD/YYYY

mois/jour/année

YYYY-DD-MM

année-jour-mois

MM-DD-YYYY

mois-jour-année

MM.DD.YYYY

mois. jour. année

Codes d'erreur

SelectObject renvoie les codes d'erreur de deux manières :

Le code d'état HTTP figure dans l'en-tête de la réponse et le code d'erreur dans le corps de la réponse, comme pour les autres requêtes OSS. Ces codes d'erreur signalent des erreurs de saisie, telles qu'une instruction SQL non valide ou des erreurs de données.
Le code d'erreur est inclus dans la trame de fin du corps de la réponse. Ces codes indiquent que les données sont incorrectes ou ne correspondent pas au type de données spécifié dans l'instruction SQL. Par exemple, une chaîne de caractères peut se trouver dans une colonne définie comme entière dans l'instruction SQL. Dans ce cas, une partie des données est traitée, puis le code d'état HTTP 206 et les données traitées sont envoyés au client.

Selon l'emplacement de la ligne erronée dans l'objet CSV, des codes d'erreur tels que InvalidCSVLine peuvent être renvoyés sous forme de code d'état HTTP dans l'en-tête de la réponse ou sous forme de code d'état dans la trame de fin.

ErrorCode

Description

HTTP Status Code

Http Status Code in End Frame

InvalidSqlParameter

Message d'erreur indiquant que le paramètre SQL spécifié n'existe pas.

L'instruction SQL de la requête est nulle, sa taille dépasse la limite supérieure ou elle n'est pas encodée en Base64.

400

Aucun

InvalidInputFieldDelimiter

Message d'erreur indiquant que l'objet CSV d'entrée contient des délimiteurs de colonne non valides.

Le paramètre n'est pas encodé en Base64 ou sa taille dépasse 1 octet après décodage.

400

Aucun

InvalidInputRecordDelimiter

Message d'erreur indiquant que l'objet CSV d'entrée contient des délimiteurs de ligne non valides. Le paramètre n'est pas encodé en Base64 ou sa taille dépasse 2 octets après décodage.

400

Aucun

InvalidInputQuote

Message d'erreur indiquant que l'objet CSV d'entrée contient des caractères de guillemet non valides. Le paramètre n'est pas encodé en Base64 ou sa taille dépasse 1 octet après décodage.

400

Aucun

InvalidOutputFieldDelimiter

Message d'erreur indiquant que l'objet CSV de sortie contient des délimiteurs de colonne non valides. Le paramètre n'est pas encodé en Base64 ou sa taille dépasse 1 octet après décodage.

400

Aucun

InvalidOutputRecordDelimiter

Message d'erreur indiquant que l'objet CSV de sortie contient des délimiteurs de ligne non valides. Le paramètre n'est pas encodé en Base64 ou sa taille dépasse 2 octets après décodage.

400

Aucun

UnsupportedCompressionFormat

Message d'erreur indiquant que la valeur du paramètre Compression n'est ni NONE ni GZIP. La casse n'est pas prise en compte.

400

Aucun

InvalidCommentCharacter

Message d'erreur indiquant que l'objet CSV contient des caractères de commentaire non valides. Le paramètre n'est pas encodé en Base64 ou sa taille dépasse 1 octet après décodage.

400

Aucun

InvalidRange

Message d'erreur indiquant que le paramètre Range n'est pas préfixé par line-range= ou split-range=, ou que la valeur de plage n'est pas conforme à la norme HTTP pour Range.

400

Aucun

DecompressFailure

Message d'erreur indiquant que la valeur de Compression est GZIP et que l'objet ne peut pas être extrait.

400

Aucun

InvalidMaxSkippedRecordsAllowed

Message d'erreur indiquant que la valeur de MaxSkippedRecordsAllowed n'est pas un entier.

400

Aucun

SelectCsvMetaUnavailable

Message d'erreur indiquant que l'objet n'inclut pas les métadonnées CSV lorsque le paramètre Range est spécifié. Appelez d'abord l'opération CreateSelectObjectMeta.

400

Aucun

InvalidTextEncoding

Message d'erreur indiquant que l'objet n'est pas encodé en UTF-8.

400

Aucun

InvalidOSSSelectParameters

Message d'erreur indiquant que les paramètres EnablePayloadCrc et OutputRawData sont définis sur true, ce qui entraîne un conflit.

400

Aucun

InternalError

Message d'erreur indiquant qu'une erreur système OSS s'est produite.

500 ou 206

500 ou Aucun

SqlSyntaxError

Message d'erreur indiquant que la syntaxe de l'instruction SQL décodée en Base64 n'est pas valide.

400

Aucun

SqlExceedsMaxInCount

Message d'erreur indiquant que le nombre de valeurs incluses dans la clause SQL IN dépasse 1 024.

400

Aucun

SqlExceedsMaxColumnNameLength

Message d'erreur indiquant que la taille du nom de colonne dépasse 1 024 octets.

400

Aucun

SqlInvalidColumnIndex

Message d'erreur indiquant que l'index de colonne dans l'instruction SQL est inférieur à 1 octet ou supérieur à 1 000 octets.

400

Aucun

SqlAggregationOnNonNumericType

Message d'erreur indiquant qu'une fonction d'agrégation est utilisée sur une colonne non numérique.

400

Aucun

SqlInvalidAggregationOnTimestamp

Message d'erreur indiquant que la fonction d'agrégation SUM ou AVG est utilisée sur une colonne d'horodatage.

400

Aucun

SqlValueTypeOfInMustBeSame

Message d'erreur indiquant que des valeurs de types différents sont incluses dans la clause SQL IN.

400

Aucun

SqlInvalidEscapeChar

Message d'erreur indiquant qu'un caractère d'échappement non valide, tel qu'un point d'interrogation (?), un signe pourcentage (%) ou un astérisque (*), est spécifié dans la clause SQL LIKE.

400

Aucun

SqlOnlyOneEscapeCharIsAllowed

Message d'erreur indiquant que la taille du caractère d'échappement dans la clause SQL LIKE dépasse 1 octet.

400

Aucun

SqlNoCharAfterEscapeChar

Message d'erreur indiquant qu'aucun caractère n'est spécifié après le caractère d'échappement dans la clause SQL LIKE.

400

Aucun

SqlInvalidLimitValue

Message d'erreur indiquant que le nombre spécifié après la clause SQL Limit est inférieur à 1.

400

Aucun

SqlExceedsMaxWildCardCount

Message d'erreur indiquant que le nombre d'astérisques (*) ou de signes pourcentage (%) dans la clause SQL LIKE dépasse la limite supérieure.

400

Aucun

SqlExceedsMaxConditionCount

Message d'erreur indiquant que le nombre d'expressions conditionnelles dans la clause SQL WHERE dépasse la limite supérieure.

400

Aucun

SqlExceedsMaxConditionDepth

Message d'erreur indiquant que la profondeur de l'arborescence conditionnelle dans la clause SQL WHERE dépasse la limite supérieure.

400

Aucun

SqlOneColumnCastToDifferentTypes

Message d'erreur indiquant qu'une colonne est convertie en différents types via la fonction CAST dans l'instruction SQL.

400

Aucun

SqlOperationAppliedToDifferentTypes

Message d'erreur indiquant qu'un opérateur est utilisé sur deux objets de types différents dans l'instruction SQL. Par exemple, ce code d'erreur est renvoyé si col1 dans _col1 > 3 est une chaîne.

400

Aucun

SqlInvalidColumnName

Message d'erreur indiquant qu'un nom de colonne utilisé dans l'instruction SQL ne figure pas dans l'en-tête de l'objet CSV.

400

Aucun

SqlNotSupportedTimestampFormat

Message d'erreur indiquant que le format d'horodatage spécifié dans la clause SQL CAST n'est pas pris en charge.

400

Aucun

SqlNotMatchTimestampFormat

Message d'erreur indiquant que le format d'horodatage spécifié dans la clause SQL CAST ne correspond pas à la chaîne d'horodatage.

400

Aucun

SqlInvalidTimestampValue

Message d'erreur indiquant qu'aucun format d'horodatage n'est spécifié dans la clause SQL CAST et que la chaîne spécifiée ne peut pas être convertie en horodatage.

400

Aucun

SqlInvalidLikeOperand

Message d'erreur indiquant que les noms ou index de colonne du côté gauche ne sont pas spécifiés dans la clause SQL LIKE, que la colonne spécifiée du côté gauche n'est pas de type chaîne ou que la colonne du côté droit dans la clause LIKE est de type chaîne.

400

Aucun

SqlInvalidMixOfAggregationAndColumn

Message d'erreur indiquant que la clause SQL SELECT inclut des noms de colonne et des index pour les fonctions d'agrégation et les fonctions sans agrégation.

400

Aucun

SqlExceedsMaxAggregationCount

Message d'erreur indiquant que le nombre de fonctions d'agrégation incluses dans la clause SQL SELECT dépasse la limite supérieure.

400

Aucun

SqlInvalidMixOfStarAndColumn

Message d'erreur indiquant qu'un astérisque (*), un nom de colonne et un index de colonne sont inclus dans la même instruction SQL.

400

Aucun

SqlInvalidKeepAllColumnsWithAggregation

Message d'erreur indiquant que l'instruction SQL inclut des fonctions d'agrégation et que le paramètre KeepAllColumns est défini sur true.

400

Aucun

SqlInvalidKeepAllColumnsWithDuplicateColumn

Message d'erreur indiquant que l'instruction SQL inclut des noms ou index de colonne répétés et que le paramètre KeepAllColumns est défini sur true.

400

Aucun

SqlInvalidSqlAfterAnalysis

Message d'erreur indiquant que l'instruction SQL est complexe et que l'instruction SQL analysée n'est pas prise en charge.

400

Aucun

InvalidArithmeticOperand

Message d'erreur indiquant que l'instruction SQL contient des opérations arithmétiques effectuées sur des constantes ou des colonnes non numériques.

400

Aucun

SqlInvalidAndOperand

Message d'erreur indiquant que les expressions jointes par l'opérateur AND dans l'instruction SQL ne sont pas de type booléen.

400

Aucun

SqlInvalidOrOperand

Message d'erreur indiquant que les expressions jointes par l'opérateur OR dans l'instruction SQL ne sont pas de type booléen.

400

Aucun

SqlInvalidNotOperand

Message d'erreur indiquant que les expressions jointes par l'opérateur NOT dans l'instruction SQL ne sont pas de type booléen.

400

Aucun

SqlInvalidIsNullOperand

Message d'erreur indiquant que l'instruction SQL spécifie des opérations basées sur l'opérateur IS NULL effectuées sur une constante.

400

Aucun

SqlComparerOperandTypeMismatch

Message d'erreur indiquant que l'instruction SQL spécifie des opérations basées sur l'opérateur de comparaison effectuées sur deux objets de types différents.

400

Aucun

SqlInvalidConcatOperand

Message d'erreur indiquant que l'instruction SQL contient deux constantes jointes par l'opérateur de concaténation (

400

Aucun

SqlUnsupportedSql

Message d'erreur indiquant que l'instruction SQL est complexe et que la taille du plan SQL généré dépasse la limite supérieure.

400

Aucun

HeaderInfoExceedsMaxSize

Message d'erreur indiquant que la taille des informations d'en-tête spécifiées dans l'instruction SQL dépasse la limite supérieure.

400

Aucun

OutputExceedsMaxSize

Message d'erreur indiquant que la taille d'une ligne dans la sortie dépasse la limite supérieure.

400

Aucun

InvalidCsvLine

Message d'erreur indiquant qu'une ligne de l'objet CSV n'est pas valide ou que sa taille dépasse la limite supérieure, ou que le nombre de lignes ignorées dépasse la valeur de MaxSkippedRecordsAllowed.

400 ou 206

400 ou Aucun

NegativeRowIndex

Message d'erreur indiquant que la valeur de l'index de tableau dans l'instruction SQL est un nombre négatif.

400

Aucun

ExceedsMaxNestedColumnDepth

Message d'erreur indiquant que le nombre de niveaux imbriqués de l'objet JSON dans l'instruction SQL dépasse la limite supérieure.

400

Aucun

NestedColumnNotSupportInCsv

Message d'erreur indiquant que l'instruction SQL contient des colonnes imbriquées avec des points (.) ou des tableaux avec des crochets ([]). Ces caractères ne sont pas pris en charge pour les instructions SQL des objets CSV.

400

Aucun

TableRootNodeOnlySupportInJson

Message d'erreur indiquant que le chemin du nœud racine n'est pas spécifié après From ossobject dans les objets JSON.

400

Aucun

JsonNodeExceedsMaxSize

Message d'erreur indiquant que la taille du nœud racine dans l'objet JSON dépasse la limite supérieure.

400 ou 206

400 ou Aucun

InvalidJsonData

Message d'erreur indiquant que les données JSON sont mal formatées.

400 ou 206

400 ou Aucun

ExceedsMaxJsonArraySize

Message d'erreur indiquant que le nombre d'éléments dans un tableau du nœud racine de l'objet JSON dépasse la limite supérieure.

400 ou 206

400 ou Aucun

WildCardNotAllowed

Message d'erreur indiquant que les astérisques (*) ne peuvent pas être utilisés dans les clauses SQL SELECT ou SQL WHERE pour l'objet JSON. Par exemple, une erreur est renvoyée si vous exécutez l'instruction suivante : select s.a.b[*] from ossobject where a.c[*] > 0.

400

Aucun

JsonNodeExceedsMaxDepth

Message d'erreur indiquant que la profondeur du nœud racine de l'objet JSON dépasse la limite supérieure.

400 ou 206

400 ou Aucun

ossutil

Pour plus d'informations sur la commande ossutil correspondant à l'opération SelectObject, consultez select-object.