swift-sdk/Sources/Hanzo/APIs/DatasetAPI.swift

//
// DatasetAPI.swift
//
// Generated by openapi-generator
// https://openapi-generator.tech
//

import Foundation

open class DatasetAPI {

    /**
     Declare the next version of a dataset
     
     - parameter riskDatasetSpec: (body)  
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RiskDataset
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func riskCreateDataset(riskDatasetSpec: RiskDatasetSpec, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> RiskDataset {
        return try await riskCreateDatasetWithRequestBuilder(riskDatasetSpec: riskDatasetSpec, apiConfiguration: apiConfiguration).execute().body
    }

    /**
     Declare the next version of a dataset
     - POST /v1/dataset
     - Declares the next version of a dataset from a bound query over this org's own feature surface.  It mints a VERSION and writes no rows: a version is declared, then materialised once, then never rewritten. Version numbers are monotone and never reused, so \"version 3 of signups\" means one thing forever — which is the whole reason a model can cite one.  The window is bounded by the source's retention, the horizon by a year, the rows by the plane's cap, and the number of datasets and versions per org by their own limits. Every refusal names which bound it hit.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter riskDatasetSpec: (body)  
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<RiskDataset> 
     */
    open class func riskCreateDatasetWithRequestBuilder(riskDatasetSpec: RiskDatasetSpec, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<RiskDataset> {
        let localVariablePath = "/v1/dataset"
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters = JSONEncodingHelper.encodingParameters(forEncodableObject: riskDatasetSpec, codableHelper: apiConfiguration.codableHelper)

        let localVariableUrlComponents = URLComponents(string: localVariableURLString)

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            "Content-Type": "application/json",
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<RiskDataset>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "POST", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }

    /**
     Describe every version of one dataset
     
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RiskDatasetVersions
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func riskDataset(name: String, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> RiskDatasetVersions {
        return try await riskDatasetWithRequestBuilder(name: name, apiConfiguration: apiConfiguration).execute().body
    }

    /**
     Describe every version of one dataset
     - GET /v1/dataset/{name}
     - Dataset describes every version of one dataset, newest first — the whole history, because the point of a version is that the older ones are still there and a model fitted last quarter cites one of them.  A name this org does not own answers 404, exactly as an unknown name does, so a probe learns nothing about another tenant's datasets.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<RiskDatasetVersions> 
     */
    open class func riskDatasetWithRequestBuilder(name: String, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<RiskDatasetVersions> {
        var localVariablePath = "/v1/dataset/{name}"
        let namePreEscape = "\(APIHelper.mapValueToPathItem(name))"
        let namePostEscape = namePreEscape.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? ""
        localVariablePath = localVariablePath.replacingOccurrences(of: "{name}", with: namePostEscape, options: .literal, range: nil)
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters: [String: any Sendable]? = nil

        let localVariableUrlComponents = URLComponents(string: localVariableURLString)

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            :
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<RiskDatasetVersions>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "GET", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }

    /**
     Show where a version's rows came from, and whether that can still be demonstrated
     
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter version: (query) Version is the version to trace. Zero takes the newest published one. (optional)
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RiskLineage
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func riskDatasetLineage(name: String, version: Int64? = nil, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> RiskLineage {
        return try await riskDatasetLineageWithRequestBuilder(name: name, version: version, apiConfiguration: apiConfiguration).execute().body
    }

    /**
     Show where a version's rows came from, and whether that can still be demonstrated
     - GET /v1/dataset/{name}/lineage
     - Shows where a version's rows came from and whether that can still be demonstrated.  The answer is MEASURED, not recalled: the plane asks the source the same bounded question again and compares it to the fingerprint taken when the version was built. Anything but exact agreement is reported as drift — the source is fed by a rollup that runs behind the events, so \"it holds more now\" is the ordinary case and it means re-running the spec would not reproduce this version. An admitted gap is actionable; an unfalsifiable claim is not.  IT IS A PRICED, BOUNDED READ, because it is the same statement a materialisation is charged for: an exact distinct-count over up to 400 days of this org's feature surface. It takes the org's ONE source-scan slot, so a tenant looping it spends one scan and not a thousand; it counts against the plane's ceiling, so the fleet's warehouse is bounded too; and it runs under this plane's own deadline rather than the caller's patience.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter version: (query) Version is the version to trace. Zero takes the newest published one. (optional)
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<RiskLineage> 
     */
    open class func riskDatasetLineageWithRequestBuilder(name: String, version: Int64? = nil, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<RiskLineage> {
        var localVariablePath = "/v1/dataset/{name}/lineage"
        let namePreEscape = "\(APIHelper.mapValueToPathItem(name))"
        let namePostEscape = namePreEscape.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? ""
        localVariablePath = localVariablePath.replacingOccurrences(of: "{name}", with: namePostEscape, options: .literal, range: nil)
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters: [String: any Sendable]? = nil

        var localVariableUrlComponents = URLComponents(string: localVariableURLString)
        localVariableUrlComponents?.queryItems = APIHelper.mapValuesToQueryItems([
            "version": (wrappedValue: version?.asParameter(codableHelper: apiConfiguration.codableHelper), isExplode: true),
        ])

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            :
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<RiskLineage>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "GET", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }

    /**
     List this org's datasets
     
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RiskDatasetList
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func riskDatasets(apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> RiskDatasetList {
        return try await riskDatasetsWithRequestBuilder(apiConfiguration: apiConfiguration).execute().body
    }

    /**
     List this org's datasets
     - GET /v1/dataset
     - Datasets lists this org's datasets, each with its newest version. An org that has declared none gets an empty list; a store that cannot be reached gets a refusal, never an empty list, because the two read identically and only one of them is true.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<RiskDatasetList> 
     */
    open class func riskDatasetsWithRequestBuilder(apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<RiskDatasetList> {
        let localVariablePath = "/v1/dataset"
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters: [String: any Sendable]? = nil

        let localVariableUrlComponents = URLComponents(string: localVariableURLString)

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            :
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<RiskDatasetList>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "GET", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }

    /**
     Dispose of one dataset and every version of it
     
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RiskDatasetDisposal
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func riskDeleteDataset(name: String, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> RiskDatasetDisposal {
        return try await riskDeleteDatasetWithRequestBuilder(name: name, apiConfiguration: apiConfiguration).execute().body
    }

    /**
     Dispose of one dataset and every version of it
     - DELETE /v1/dataset/{name}
     - Disposes of one dataset and every version of it: the rows are dropped and the register is marked with what went.  This is the ONLY expiry in this plane. Neither table carries a TTL, deliberately: a table TTL is a fleet-wide clock no tenant can hold longer or shorten, which is the opposite of a retention decision belonging to the tenant whose records they are. The drop is a partition drop on (org, dataset), so the tenant is the first component of the thing being dropped and a disposal cannot be spelled across one.  The BYTES are what goes. The register keeps one `disposed` row per version — the name, the number, the spec, the digest and who disposed of it when — for two reasons: a retention obligation is answered by a record of the deletion, not by silence; and version numbers must stay monotone, so that after `orders` is disposed of and declared again the next version is 4 and not 1. A number that could be reused would make every citation of `orders v3` ambiguous forever.  It is not reversible and there is no soft state in between. A version a model cited has no rows once this returns, and every read of it says so.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<RiskDatasetDisposal> 
     */
    open class func riskDeleteDatasetWithRequestBuilder(name: String, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<RiskDatasetDisposal> {
        var localVariablePath = "/v1/dataset/{name}"
        let namePreEscape = "\(APIHelper.mapValueToPathItem(name))"
        let namePostEscape = namePreEscape.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? ""
        localVariablePath = localVariablePath.replacingOccurrences(of: "{name}", with: namePostEscape, options: .literal, range: nil)
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters: [String: any Sendable]? = nil

        let localVariableUrlComponents = URLComponents(string: localVariableURLString)

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            :
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<RiskDatasetDisposal>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "DELETE", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }

    /**
     Read a version's rows back, one page at a time
     
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter version: (query) Version is the version to read. Zero takes the newest published one. (optional)
     - parameter split: (query) Split narrows to train, val or test. Empty reads every split. (optional)
     - parameter offset: (query) Offset is where the page starts, in the version&#39;s own row order (by id, which is derived from the row and therefore stable forever). (optional)
     - parameter limit: (query) Limit is how many rows to return. Zero and anything above the plane&#39;s bound take the bound. (optional)
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RiskDatasetRows
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func riskExportDataset(name: String, version: Int64? = nil, split: String? = nil, offset: Int64? = nil, limit: Int64? = nil, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> RiskDatasetRows {
        return try await riskExportDatasetWithRequestBuilder(name: name, version: version, split: split, offset: offset, limit: limit, apiConfiguration: apiConfiguration).execute().body
    }

    /**
     Read a version's rows back, one page at a time
     - GET /v1/dataset/{name}/export
     - Reads a published version's rows back, one bounded page at a time, in the version's own stable row order.  Only a published version can be exported. Rows written by an attempt that never completed are inert — no register row names them — and they are disposed of with the dataset.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter version: (query) Version is the version to read. Zero takes the newest published one. (optional)
     - parameter split: (query) Split narrows to train, val or test. Empty reads every split. (optional)
     - parameter offset: (query) Offset is where the page starts, in the version&#39;s own row order (by id, which is derived from the row and therefore stable forever). (optional)
     - parameter limit: (query) Limit is how many rows to return. Zero and anything above the plane&#39;s bound take the bound. (optional)
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<RiskDatasetRows> 
     */
    open class func riskExportDatasetWithRequestBuilder(name: String, version: Int64? = nil, split: String? = nil, offset: Int64? = nil, limit: Int64? = nil, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<RiskDatasetRows> {
        var localVariablePath = "/v1/dataset/{name}/export"
        let namePreEscape = "\(APIHelper.mapValueToPathItem(name))"
        let namePostEscape = namePreEscape.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? ""
        localVariablePath = localVariablePath.replacingOccurrences(of: "{name}", with: namePostEscape, options: .literal, range: nil)
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters: [String: any Sendable]? = nil

        var localVariableUrlComponents = URLComponents(string: localVariableURLString)
        localVariableUrlComponents?.queryItems = APIHelper.mapValuesToQueryItems([
            "version": (wrappedValue: version?.asParameter(codableHelper: apiConfiguration.codableHelper), isExplode: true),
            "split": (wrappedValue: split?.asParameter(codableHelper: apiConfiguration.codableHelper), isExplode: true),
            "offset": (wrappedValue: offset?.asParameter(codableHelper: apiConfiguration.codableHelper), isExplode: true),
            "limit": (wrappedValue: limit?.asParameter(codableHelper: apiConfiguration.codableHelper), isExplode: true),
        ])

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            :
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<RiskDatasetRows>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "GET", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }

    /**
     Materialise the declared version into immutable rows
     
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RiskDataset
     */
    @available(macOS 10.15, iOS 13.0, tvOS 13.0, watchOS 6.0, *)
    open class func riskMaterializeDataset(name: String, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) async throws(ErrorResponse) -> RiskDataset {
        return try await riskMaterializeDatasetWithRequestBuilder(name: name, apiConfiguration: apiConfiguration).execute().body
    }

    /**
     Materialise the declared version into immutable rows
     - POST /v1/dataset/{name}/materialize
     - Builds the declared version into immutable rows and answers 202 as soon as the attempt is on record.  It never holds the request open for the work: a materialisation is a bounded warehouse scan, and letting an HTTP client's timeout be a data plane's timeout is how one tenant's retry loop becomes everyone's outage. ONE materialisation runs per org at a time; a second is refused rather than queued, because a queue admits the same work later and the honest answer to \"again\" while one is running is that one is running.  Only a DECLARED version is admitted. A published version is immutable, and a version whose earlier attempt did not complete is never re-attempted — that would union two runs' rows under one number and make the digest a lie. In both cases the answer is to declare a new version, which is what a second run over a moving source honestly is.
     - Bearer Token:
       - type: http
       - name: bearer
     - parameter name: (path) Name is the dataset, from the path. 
     - parameter apiConfiguration: The configuration for the http request.
     - returns: RequestBuilder<RiskDataset> 
     */
    open class func riskMaterializeDatasetWithRequestBuilder(name: String, apiConfiguration: HanzoAPIConfiguration = HanzoAPIConfiguration.shared) -> RequestBuilder<RiskDataset> {
        var localVariablePath = "/v1/dataset/{name}/materialize"
        let namePreEscape = "\(APIHelper.mapValueToPathItem(name))"
        let namePostEscape = namePreEscape.addingPercentEncoding(withAllowedCharacters: .urlPathAllowed) ?? ""
        localVariablePath = localVariablePath.replacingOccurrences(of: "{name}", with: namePostEscape, options: .literal, range: nil)
        let localVariableURLString = apiConfiguration.basePath + localVariablePath
        let localVariableParameters: [String: any Sendable]? = nil

        let localVariableUrlComponents = URLComponents(string: localVariableURLString)

        let localVariableNillableHeaders: [String: (any Sendable)?] = [
            :
        ]

        let localVariableHeaderParameters = APIHelper.rejectNilHeaders(localVariableNillableHeaders)

        let localVariableRequestBuilder: RequestBuilder<RiskDataset>.Type = apiConfiguration.requestBuilderFactory.getBuilder()

        return localVariableRequestBuilder.init(method: "POST", URLString: (localVariableUrlComponents?.string ?? localVariableURLString), parameters: localVariableParameters, headers: localVariableHeaderParameters, requiresAuthentication: true, apiConfiguration: apiConfiguration)
    }
}