graphql-engine/v3/rfcs/open-dd-field-argument-types-changes.md

Open DD field arguments

Motivation

With the introduction of field arguments in NDC spec v0.1.3, v3-engine is now unblocked to support field level arguments. For example, the following GraphQL queries can be supported now:

query {
  Artist(limit: 10) {
    Name(full: true) # return full name
    ArtistId
    CryptoHash(algorithm: SHA1)
  }
}

For this we need to support field arguments for OpenDD ObjectType kind.

Apart from the field argument definition (used for preparing the graphql schema), we also need to define the field argument mapping as well (similar to how we define the fieldMapping). The mappings will be used while preparing the ndc query for a given query with field arguments.

Proposal

There are a lot of ways in which this can be implemented:

1. Add a new OpenDD kind called FieldArgument:

   kind: FieldArgument
   version: v1
   definition:
     name: Artist_Name_Field_Argument
     arguments:
       - name: full
         argumentType: Bool
       - name: initialsOnly
         argumentType: Bool
       - name: truncateAfter
         argumentType: Int
     dataConnectorArgumentsMapping:
       - dataConnectorName: pg_1
         dataConnectorObjectType: artist
         dataConnectorFieldName: name
         argumentMapping:
           full: full_name
           initialsOnly: convert_to_initials
           truncateAfter: truncate_length
   

   This approach is going to result in a lot of new OpenDD metadata objects being added to an already humongous hml file. This will be tedious to maintain (imagine removing an ObjectType and missing one of the many FieldArgument).

   Moreover the field arguments seems like a thing that should be defined while defining the OpenDD ObjectType for the NDC object type. Thus, we have the next proposal.

2. Extend the ObjectType:

   kind: ObjectType
   version: v1
   definition:
     name: Artist
     graphql:
       typeName: artist
       inputTypeName: artistInput
       apolloFederation:
         keys:
           - fields:
               - ArtistId
     fields:
       - name: ArtistId
         type: int4!
       - name: Name
         type: varchar
         arguments:
           - name: full
             argumentType: Bool
           - name: initialsOnly
             argumentType: Bool
           - name: truncateAfter
             argumentType: Int
       - name: CryptoHash
         type: varchar
         arguments:
           - name: algorithm
             argumentType: varchar!
     dataConnectorTypeMapping:
       - dataConnectorName: db
         dataConnectorObjectType: Artist
         fieldMapping:
           ArtistId:
             column:
               name: ArtistId
           Name:
             column:
               name: Name
             argumentMapping:
               full: full_name
               initialsOnly: convert_to_initials
               truncateAfter: truncate_length
           CryptoHash:
             column:
               name: hash
             argumentMapping:
               - algorithm: algo
   

What all will change?

Assuming we are going with the 2nd proposal (extending the ObjectType)

1. We will add a new field arguments (in definition.fields[i]) containing the definition for the arguments for the field. The definition for an argument consists of the following:
   1. Name of the argument (this will be used as the graphql name for the input field)
   2. Argument type: The graphql type for the argument.
   3. (Optional) Default value
2. We will also add a new field argumentMapping (in definition.dataConnectorTypeMapping[i].fieldMapping.<field>). The argument mapping will define the mapping between the arguments defined in the definition (1) to the data connector argument names.