/*
 * Copyright (2021) The Delta Lake Project Authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
syntax = "proto2";

package io.delta.sharing.server.protocol;

import "scalapb/scalapb.proto";

option java_package = "io.delta.sharing.server.protocol";

option java_generate_equals_and_hash = true;
option (scalapb.options).flat_package = true;

// Define the JSON objects used by REST APIs. The table metadata format is not defined in this file
// because it requires Map type which is not supported by Protocol Buffers Version 2.

message Share {
    optional string name = 1;
}

message Schema {
    optional string name = 1;
    optional string share = 2;
}

message Table {
    optional string name = 1;
    optional string schema = 2;
    optional string share = 3;
    optional string id = 4;
}

message QueryTableRequest {
    repeated string predicateHints = 1;
    optional string jsonPredicateHints = 6;
    optional int64 limitHint = 2;
    // The maximum number of files to return in one page. This is a hint for the server,
    // and the server may not honor it. The server that supports pagination should return
    // no more than this limit, but it can return fewer. If there are more files available,
    // a nextPageToken will be returned to the user to retrieve the next page.
    optional int32 maxFiles = 9;
    // The page token used to retrieve the subsequent page.
    optional string pageToken = 10;
    // Whether or not to return a refresh token in the response. Only used in latest snapshot query
    // AND first page query. For long running queries, delta sharing spark may make additional request
    // to refresh pre-signed urls, and there might be table changes between the initial request and
    // the refresh request. The refresh token will contain version information to make sure that
    // the refresh request returns the same set of files.
    optional bool includeRefreshToken = 11;
    // The refresh token used to refresh pre-signed urls. Only used in latest snapshot query AND
    // first page query.
    optional string refreshToken = 12;

    // Only one of the three parameters can be supported in a single query.
    // If none of them is specified, the query is for the latest version.
    //
    // - If either version or timestamp is specified, the query is for the snapshot at the version.
    // - If startingVersion is specified, the query is for all dataChange files from startingVersion
    //   until the current version.
    // The table version being queried.
    optional int64 version = 3;
    // The table version corresponding to the timestamp being queried.
    optional string timestamp = 4;
    // Query all data change files since startingVersion, inclusive.
    optional int64 startingVersion = 5;
    // Query all data change files until endingVersion, inclusive. Only used when startingVersion
    // is set, otherwise will be ignored.
    optional int64 endingVersion = 7;

    // TODO: update this. The format of the response, supported formats: parquet, delta.
    optional bool queryDeltaLog = 8;

    // idempotency key for the query request, this is required for async query
    optional string idempotency_key = 14;

    // The columns to be returned in the response for view query.
    // If not specified, all columns will be returned.
    repeated string requested_columns = 15;

    // Whether to include historical Protocol actions seen in the delta log when serving a
    // streaming version-range query (startingVersion is set). When true, intermediate Protocol
    // actions in the log range are inlined alongside the file actions for protocol /
    // reader-feature compatibility checks. Only effective for responses with
    // responseformat=delta; ignored for parquet responses.
    optional bool includeHistoricalProtocol = 16;
}

message GetQueryInfoRequest {
    optional string query_id = 1;

    // The maximum number of files to return in one page. This is a hint for the server,
    // and the server may not honor it. The server that supports pagination should return
    // no more than this limit, but it can return fewer. If there are more files available,
    // a nextPageToken will be returned to the user to retrieve the next page.
    optional int32 max_files = 2;

    // The page token used to retrieve the subsequent page.
    optional string page_token = 3;
}

message ListSharesResponse {
    repeated Share items = 1;
    optional string next_page_token = 2;
}

message GetShareResponse {
    optional Share share = 1;
}

message ListSchemasResponse {
    repeated Schema items = 1;
    optional string next_page_token = 2;
}

message ListTablesResponse {
    repeated Table items = 1;
    optional string next_page_token = 2;
}

message ListAllTablesResponse {
    repeated Table items = 1;
    optional string next_page_token = 2;
}

// Define a special class to generate the page token for pagination. It includes the information we
// need to know where we should start to query, and check whether the page token comes from the
// right result. For example, we would like to throw an error when the user uses a page token
// returning from ListShares and uses it in ListSchemas REST API.
message PageToken {
    optional string id = 1;
    optional string share = 2;
    optional string schema = 3;
}

// Define a special class to generate the page token for pagination. It includes the information
// about where we should start to query, and checks whether the paginated request is valid.
message QueryTablePageToken {
    // Id of the table being queried.
    optional string id = 1;
    // Only used in queryTable at snapshot, refers to the version being queried.
    optional int64 version = 2;
    // Only used in queryTable from starting_version and queryTableChanges.
    // The table version where the querying process starts in next page, inclusive.
    optional int64 starting_version = 3;
    // Only used in queryTable from starting_version and queryTableChanges.
    // The table version where the querying process ends in next page, inclusive.
    optional int64 ending_version = 4;
    // The checksum of other query parameters. This is used for validation purpose, as the user
    // is expected to keep all other parameters to the request the same.
    optional string checksum = 5;
    // The local index of the first action in next page.
    // For queryTable at snapshot, (version, starting_action_index) determines the entry point
    // of the next page.
    // For queryTable from starting_version and queryTableChanges,
    // (starting_version, starting_action_index) determines the entry point of the next page.
    optional int32 starting_action_index = 6;
    // The expiration timestamp of the page token in milliseconds.
    optional int64 expiration_timestamp = 7;
    // The latest version of the table when the first page request is received.
    optional int64 latest_version = 8;
}

// Define a special class to generate the refresh token for latest snapshot query.
message RefreshToken {
    // Id of the table being queried.
    optional string id = 1;
    // Only used in queryTable at snapshot, refers to the version being queried.
    optional int64 version = 2;
    // The expiration timestamp of the refresh token in milliseconds.
    optional int64 expiration_timestamp = 3;
}