github.com/attic-labs/noms@v0.0.0-20210827224422-e5fa29d95e8b/go/ngql/README.md (about)

     1  # Noms GraphQL
     2  
     3  An experimental bridge between Noms and [GraphQL](http://graphql.org/)
     4  
     5  This is to be used with https://github.com/attic-labs/graphql which is a fork of https://github.com/graphql-go/graphql to handle Noms values. It disables some validations that do not work for Noms due to Noms being schemaless (or more precisely  the schema is a function of the value in the dataset).
     6  
     7  *ngql* provides an API to convert Noms types/values to and from GraphQL types/values, as well as some functions that can be used to implement a GraphQL endpoint using https://github.com/attic-labs/graphql.
     8  
     9  # Status
    10  
    11   * All Noms types are supported except
    12     * Blob
    13     * Type
    14     * Unions with non-`Struct` component types
    15     * GraphQL does not support unions in input types which limits the input types that can be used.
    16  
    17  # Type conversion rules
    18  
    19  ## Value
    20  
    21  Allmost all Noms values can be represented by GraphQL. All Noms values except the primitives (`Bool`, `Number` & `String`) are represented by a GraphQL struct.
    22  
    23  ## Bool
    24  
    25  Is represented by a non nullable `Bool`
    26  
    27  ## Number
    28  
    29  Is represented by a non nullable `Float`
    30  
    31  ## String
    32  
    33  Is represented by a non nullable `String`
    34  
    35  ## List
    36  
    37  Noms lists are expressed as a GraphQL struct with the fields
    38  
    39  * `values` - The values in the list.
    40  * `size` - The number of values in the list.
    41  
    42  Lists takes a few optional arguments:
    43  
    44  * `at` - The index to start at, defaults to `0`.
    45  * `count` - The number of values to return, defaults to all of the values.
    46  
    47  ```graphql
    48  type FooList {
    49    size: Float!
    50    values: [Foo!]!
    51  }
    52  ```
    53  
    54  ## Set
    55  
    56  Noms sets are expressed as a GraphQL struct with the fields
    57  
    58  * `values` - The values in the set.
    59  * `size` - The number of values in the set.
    60  
    61  Sets takes a few optional arguments:
    62  
    63  * `at` - The index to start at, defaults to `0`.
    64  * `count` - The number of values to return, defaults to all of the values.
    65  * `key` - The value to start at.
    66  * `through` - The value to end at (inclusive).
    67  * `keys` - When provided only values that matches the keys are included in the result.
    68  
    69  ```graphql
    70  type FooSet {
    71    size: Float!
    72    values: [Foo!]!
    73  }
    74  ```
    75  
    76  ## Map
    77  
    78  Noms maps are expressed as a GraphQL struct with the fields
    79  
    80  * `values` - The values in the map.
    81  * `keys` - The keys in the map.
    82  * `entries` - The entries in the map. An entry is a struct with `key` and `value` fields.
    83  * `size` - The number of values in the map.
    84  
    85  Sets takes a few optional arguments:
    86  
    87  * `at` - The index to start at, defaults to `0`
    88  * `count` - The number of elements to return, defaults to all of the elements.
    89  * `key` - The value to start at
    90  * `through` - The value to end at (inclusive)
    91  * `keys` - When provided only values/keys/entries that matches the keys are included in the result.
    92  
    93  ```graphql
    94  type StringFooMap {
    95    size: Float!
    96    elements: [StringFooEntry!]!
    97  }
    98  
    99  type StringFloatEntry {
   100    key: String!
   101    value: Float!
   102  }
   103  ```
   104  
   105  ## Struct
   106  
   107  Noms structs are expressed as GraphQL structs, with an extra `hash` field.
   108  
   109  If the field in the Noms struct is optional then the GraphQL type for that field is nullable.
   110  
   111  ## Ref
   112  
   113  Noms refs are expressed as a GraphQL struct with a `targetHash` and `targetValue` field.
   114  
   115  ```graphql
   116  type FooRef {
   117    targetHash: String!
   118    targetValue: Foo!
   119  }
   120  ```