Contact UsGet started
© 2024 Direct Cursus Technology L.L.C.

selectObjectContent method

Written by
Updated at September 30, 2024

Filters and returns the contents of an Object Storage object based on an S3 Select query.

Warning

To be able to run S3 Select queries, contact support. You must also have the s3:GetObject permission. For more information, see Bucket policy.

Supported features of objects you can apply a query to:

  • Objects in CSV, JSON, and Parquet formats are supported.

  • UTF-8 encoded objects are supported.

  • GZIP and BZIP2 compression methods are supported for CSV files. For Parquet files, columnar compression with GZIP, Snappy, and ZSTD algorithms is supported.

  • Objects can be protected by server-side encryption.

For objects that are encrypted with managed encryption keys stored in YC Key Management Service (SSE-KMS), server-side encryption is performed transparently. This means you don't need to specify anything else.

For more information on getting started with the API and the general request format, see How to use the S3 API.

Request

POST /{bucket}/{key}?select&select-type=2 HTTP/2

Path parameters

Parameter Description
bucket Bucket name.
key Object key.

Query parameters

Parameter Description
select Required parameter that indicates the type of operation.
select-type Optional parameter to indicate the type of request.

Headers

Use the appropriate common headers in your request.

Data schema

Request parameters are passed in XML format:

<SelectObjectContentRequest xmlns="http://s3.amazonaws.com/doc/2006-03-01/">
   <Expression>string</Expression>
   <ExpressionType>string</ExpressionType>
   <RequestProgress>
      <Enabled>boolean</Enabled>
   </RequestProgress>
   <InputSerialization>
      <CompressionType>string</CompressionType>
      <CSV>
         <AllowQuotedRecordDelimiter>boolean</AllowQuotedRecordDelimiter>
         <Comments>string</Comments>
         <FieldDelimiter>string</FieldDelimiter>
         <FileHeaderInfo>string</FileHeaderInfo>
         <QuoteCharacter>string</QuoteCharacter>
         <QuoteEscapeCharacter>string</QuoteEscapeCharacter>
         <RecordDelimiter>string</RecordDelimiter>
      </CSV>
      <JSON>
         <Type>string</Type>
      </JSON>
      <Parquet>
      </Parquet>
   </InputSerialization>
   <OutputSerialization>
      <CSV>
         <FieldDelimiter>string</FieldDelimiter>
         <QuoteCharacter>string</QuoteCharacter>
         <QuoteEscapeCharacter>string</QuoteEscapeCharacter>
         <QuoteFields>string</QuoteFields>
         <RecordDelimiter>string</RecordDelimiter>
      </CSV>
      <JSON>
         <RecordDelimiter>string</RecordDelimiter>
      </JSON>
   </OutputSerialization>
   <ScanRange>
      <End>long</End>
      <Start>long</Start>
   </ScanRange>
</SelectObjectContentRequest>
Tag Description
SelectObjectContentRequest Root-level tag used to provide response parameters.

Required: Yes.

Path: /SelectObjectContentRequest.
Expression SQL expression used to request object data.

Data type: string.

Required: Yes.

Path: /SelectObjectContentRequest/Expression.
ExpressionType Expression type used for the request.

Data type: string.

Acceptable values: SQL.

Required: Yes.

Path: /SelectObjectContentRequest/ExpressionType.
InputSerialization Description of data format in the requested object.

Data type: InputSerialization.

Required: Yes.

Path: /SelectObjectContentRequest/InputSerialization.
OutputSerialization Description of the returned data format.

Data type: OutputSerialization.

Required: Yes.

Path: /SelectObjectContentRequest/OutputSerialization.
RequestProgress Indicates whether regular notifications on request progress should be enabled.

Data type: RequestProgress.

Required: No.

Path: /SelectObjectContentRequest/RequestProgress.
ScanRange Specifies the byte range of the object to get the records from. A record is processed when its first byte is contained in the range. It is used only for objects in CSV format.

Data type: ScanRange.

Required: No.

Path: /SelectObjectContentRequest/ScanRange.

Response

Headers

Responses can only contain common response headers.

Response codes

For a list of possible responses, see Responses.

A successful response contains additional data in XML format with the schema described below.

Data schema

<Payload>
   <Records>
      <Payload>blob</Payload>
   </Records>
   <Stats>
      <Details>
         <BytesProcessed>long</BytesProcessed>
         <BytesReturned>long</BytesReturned>
         <BytesScanned>long</BytesScanned>
      </Details>
   </Stats>
   <Progress>
      <Details>
         <BytesProcessed>long</BytesProcessed>
         <BytesReturned>long</BytesReturned>
         <BytesScanned>long</BytesScanned>
      </Details>
   </Progress>
   <Cont>
   </Cont>
   <End>
   </End>
</Payload>
Tag Description
Payload Root-level tag used for providing response parameters.

Path: /Payload.
Cont Message indicating that the request is being processed.

Path: /Payload/Cont.
End Message indicating that the request has been processed.

Path: /Payload/End.
Progress Information about request progress.

Path: /Payload/Progress.
Records Request result.
Path: /Payload/Records.
Stats Statistics on processed data. It is sent once at the end of the request.
Path: /Payload/Stats.

See also

Previous
options
Next
putObjectRetention