Right now our design looks like calling single function which takes all of the view parameters inferred from View definition

Internally its hardcoded definition for 1 to 4 number of parameters:

instance
  ( KnownSymbol name
  ) => InterpretableTable (View name columns '[Parameter paramName (chType :: Type)])
  where
  type TableInterpreter (View name columns '[Parameter paramName chType]) = Parameter paramName chType -> View name columns '[]
  interpretTable MkParameter{renderedParameter} =
    MkView
      { viewName = (BS.byteString . BS8.pack . symbolVal @name) Proxy
      , inpterpretedParameters = [renderedParameter]
      }


instance
  ( KnownSymbol name
  ) => InterpretableTable 
    ( View
      name
      columns
     '[ Parameter paramName chType
      , Parameter paramName2 chType2
      ]
    )
  where

  type TableInterpreter
    ( View
      name
      columns
     '[ Parameter paramName chType
      , Parameter paramName2 chType2
      ]
    ) 
    =  Parameter paramName chType
    -> Parameter paramName2 chType2
    -> View name columns '[]
  interpretTable parameter1 parameter2 =
    MkView
      { viewName = (BS.byteString . BS8.pack . symbolVal @name) Proxy
      , inpterpretedParameters = [renderedParameter parameter1, renderedParameter parameter2]
      }

-- The same code for 3 and 4 parameters
...

We need to reduce code duplication and provide a nice and stable interface for any number of view arguments

It's a great approach to make examples written as compilable markdown-compatible lhs files since we could have validated examples of our API written in markdown. It could be done via markdown support plugin for Literate Haskell markdown-unlit. It would open for us an ability to generate actual library API documentation.

I think it would be great to make two example cabal projects as first step:

1. Writing into the table
2. Reading from the parametrized view

The problems description

Right now we have an awkward library API for the ClickHouse HTTP Interface
Which brings us to the next problems:

1. We should write heavy hardcoded extensions of general interpretClient function for every ClickHouse HTTP interface usage patterns. And then use function interpretClient by specifying the extension.
2. Every extension of interpretClient function repeats injections of ClickHouse HTTP interface parts

ClickHouse HTTP interface usage patterns

Reading

Every reading process has the following general steps:

1. Client sends request with statement and auth data to a DBMS server
2. DBMS server handles statement and responses with the formatted data or an error message in http-body
3. Client handles result of database response

flowchart LR
        http-client

        subgraph request
            http-request[[http-request
                <hr>headers: user, password, database,... 
                        body: statement
                        ]]
        end

  
        dbms-server --> isSuccess
        isSuccess --> |yes| success-http-response
        isSuccess --> |no| error-http-response
        error-http-response --> http-client
        success-http-response --> http-client
    
        http-client --> http-request
        dbms-server
        subgraph response
            isSuccess{is success}
            success-http-response[[http-response <hr> body: formatted data]]
            error-http-response[[http-response <hr> body: error message]]
        end
        http-request --> dbms-server

Writing

 
flowchart LR

      http-client

      subgraph request
        http-request[[http-request
        <hr>headers: user, password, database,... 
                body: statement+formatted data]]
      end
      dbms-server --> isSuccess
      isSuccess --> |yes| success-http-response
      isSuccess --> |no| error-http-response
      error-http-response --> http-client
      success-http-response --> http-client
      http-request --> dbms-server

      dbms-server
      subgraph response
        isSuccess{is success}
        success-http-response[[http-response <hr> body: empty]]
        error-http-response[[http-response <hr> body: error message]]
      end
      http-client --> http-request

Solutions

1. We should provide a single function per usage case of HTTP interface which is independent from chosen Haskell HTTP client implementation.
2. Provide functions for injecting HTTP interface usage cases into chosen Request and Response types

Our (de)serialization code makes a lot of arrays manipulation since we need to work with escaping. It also makes code harder to understand and degrades performance. Rewriting the parsing and serialization to work with RowBinary format would make the code much more performant and simpler

API changes from other branches doesn't testing for API backward compatibility and could break docs examples in master