Execute SQL Statement on an Object

Updated at：2025-11-03

API description

This API is designed to execute SQL statements on specified objects in the Bucket and return the selected content. The requester must have read permission for the selected object. Before using SelectObject, ensure the corresponding bucket and object exist. For details, refer to the SelectObject Developer Documentation.

Details of Message Format:

The prelude part consists of 8 bytes in total: The first 4 bytes indicate the total length of the message, and the last 4 bytes indicate the total length of the header. The total length of chunk (value stored in the first 4 bytes of prelude) - total length of header - 8 bytes of prelude - 4 byte of crc32 = total length of payload data; crc32 indicates the erasure code of the entire message

Headers include custom <key,value>: "message-type": {"Records", "Cont", "End"}; "error-code": specific error code; "error-message": "detailed error message".

Payload indicates returned raw data in any format. Continuation message Payload includes BytesScanned and BytesReturned fields indicating the select progress.

Request URI

POST /v1/{bucketName}/{objectKey}?select

Parameter name	Parameter type	Required or not	Description	Example value	Parameter location
bucketName	String	Yes	Bucket name	"bucketName_example"	Path
objectKey	String	Yes	Object name	"objectKey_example"	Path
type	String	Yes	The target object type for select, currently supporting json/csv	"type_example"	Query

Parameters of request body

Description of the data structure of request body fields

Parameter name	Parameter type	Required or not	Description	Example value
selectRequest	SelectRequest	Yes	The root node of the JSON body

Description of SelectRequest field data structure

Parameter name	Parameter type	Required or not	Description	Example value
expression	String	Yes	sql statements encoded in Base64	c2VsZWN0IGNvdW50KCopIGZyb20gbxkl2JqZWN0IHdoZXJlIF80ID4gNDU=
expressionType	String	Yes	The syntax type of the query statement only supports "SQL"	SQL
inputSerialization	InputSerialization	Yes	Input stream node, whose child nodes describe the format information of the object to be queried
outputSerialization	OutputSerialization	Yes	Output stream node, whose child nodes describe the return format information of the query results
requestProgress	RequestProgress	No	+ requestProgress No - The progress information node for the select operation. The child nodes of the node describe the execution progress of the select operation, and periodically return the information to the user every 3 seconds

Description of InputSerialization field data structure

Parameter name	Parameter type	Required or not	Description	Example value
compressionType	String	No	Specify whether the queried object is compressed, with optional values "NONE" or "GZIP"	NONE
csv	Csv	No	csv node, the child nodes of which describe relevant information about the CSV file

Description of CSV field data structure

Parameter name	Parameter type	Required or not	Description	Example value
fileHeaderInfo	String	No	Option NONE/IGNORE/USE, specifying the header information in the first line of the CSV file. The default value NONE indicates no header information, IGNORE indicates that header information exists but is ignored. Both NONE and IGNORE mean that only column number can be used to extract a specific column; USE indicates the usage of header information, where only header names can be used to extract a specific column	NONE
recordDelimiter	String	No	Specify the line separator for CSV files, encoded in Base64. The default value is \n (optional), with a maximum of 2 characters, such as \r\n	\r\n
fieldDelimiter	String	No	Specify the delimiter for CSV files, encoded in Base64. The default value is , (optional), with a maximum of 1 character, such as ;	;
quoteCharacter	String	No	Specify the quote character for CSV files, encoded in Base64. The line breaks and column delimiters within quotes in the CSV file will be considered ordinary characters. The default value is double quotes " (optional), with a maximum of 1 character, such as single quotes '	'
commentCharacter	String	No	Specify the comment character of the CSV file, encoded in Base64. Lines starting with this character can be ignored; the default value is # (optional), with a maximum of 2 characters, such as //.	//

Description of OutputSerialization field data structure

Parameter name	Parameter type	Required or not	Description	Example value
outputHeader	Boolean	No	Output CSV header information at the beginning of the result; it is defaulted to false; it requires the fileHeaderInfo field value to be USE. When this value is true, corresponding CSV header names will be added in the first line of each Records message in the response results; options are false/true	false
csv	Csv	No	CSV node, the child nodes of which describe relevant information about the CSV data returned

Description of RequestProgress field data structure

Parameter name	Parameter type	Required or not	Description	Example value
enabled	Boolean	No	Describe whether the periodic return of progress information is required, with options false/true. If data filtering is time-consuming and may cause a 504 timeout, setting this to true can maintain the HTTP connection	false

Response body parameters

Description of the data structure of response body fields

Request example

                JSON
                
            

                POST /v1/bucketName_example/objectKey_example?select&type=type_example
 <Common request headers>
{
  "selectRequest" : {
    "outputSerialization" : {
      "outputHeader" : false,
      "csv" : {
        "quoteFields" : "ALWAYS",
        "recordDelimiter" : "Cg==",
        "quoteCharacter" : "Ig==",
        "fieldDelimiter" : "LA=="
      }
    },
    "expression" : "c2VsZWN0IGNvdW50KCopIGZyb20gbxkl2JqZWN0IHdoZXJlIF80ID4gNDU=",
    "expressionType" : "SQL",
    "requestProgress" : {
      "enabled" : false
    },
    "inputSerialization" : {
      "csv" : {
        "fileHeaderInfo" : "NONE",
        "recordDelimiter" : "\\r\\n",
        "quoteCharacter" : "'",
        "fieldDelimiter" : ";",
        "commentCharacter" : "//"
      },
      "compressionType" : "NONE"
    }
  }
}
            

Response example

                JSON
                
                HTTP/1.1 200 OK
 <Common response headers>
{ }

Error code

Please refer to the general error codes

Permission control

MoonBox Physical Migration Device

BOS

BOS