ann-server/api.yml at master · JasonTam/ann-server · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
swagger: "2.0"
info:
  version: 0.0.1
  title: Approximate Nearest Neighbor [ANN] Server
host: localhost:8000

paths:
  /:
    get:
      summary: Healthcheck for service
      responses:
        "200":
          description: An array of loaded ANN indexes (Healthcheck)
          schema:
            type: array
            items:
              type: string
            example: ["INDEX-0","INDEX-1","INDEX-2"]
  /tmp:
    get:
      summary: Get size of /tmp
      responses:
        "200":
          description: Size of /tmp in megabytes
          schema:
            type: int
            example: 256
  /sleep:
    get:
      summary: Sleep for `duration` milliseconds
      parameters:
        - name: duration
          description: duration in milliseconds to sleep
          type: string
  /ann/{indexName}:
    get:
      summary: Healthcheck for specific ANN index
      operationId: showAnnByName
      parameters:
        - name: indexName
          in: path
          required: true
          description: The name of the ANN index
          type: string
      responses:
        "200":
          description: ANN Metadata (Healthcheck)
          schema:
            $ref: '#/definitions/ann_summary'

  /ann/{indexName}/query:
    post:
      summary: Query the ANN index for neighbors
      operationId: queryAnn
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - name: indexName
          in: path
          required: true
          description: The name of the ANN index
          type: string
        - name: idsPayload
          in: body
          description: Query payload
          schema:
            $ref: '#/definitions/query_payload'
      responses:
        "200":
          description: list of neighbors
          schema:
            $ref: '#/definitions/entity_ids'

  /crossq:
    get:
      summary: Query the ANN with an entry from another ANN index
      operationId: crossQueryAnn
      produces:
        - application/json
      parameters:
        - name: q_name
          required: true
          description: The name of the ANN index to grab query *from*
          type: string
        - name: q_id
          required: true
          description: Name of the particular record to use as the query
            (must be a member of the `q_name` index)
          type: string
        - name: catalog_name
          required: true
          description: The name of the ANN index to apply query *to*
          type: string
        - name: k
          required: true
          description: number of neighbors to get
          type: int
        - name: incl_dist
          required: true
          description: if true, include associated distances
          type: bool
      responses:
        "200":
          description: list of neighbors
          schema:
            oneOf:
              - $ref: '#/definitions/entity_ids'
              - $ref: '#/definitions/entity_ids_w_dists'

  /ann/{indexName}/refresh:
    post:
      summary: Reload the particular ANN index (may take some time)
      operationId: reloadAnn
      parameters:
        - name: indexName
          in: path
          required: true
          description: The name of the ANN index
          type: string
      responses:
        "200":
          description: Index successfully reloaded

definitions:
  entity_id:
    type: string
    example: '123'
  entity_id_w_dist:
    type: array
    example: ["123", 0.9]
  entity_ids:
    type: array
    items:
      $ref: '#/definitions/entity_id'
    example: [ "123", "456", "789"]
  entity_ids_w_dists:
    type: array
    items:
      $ref: '#/definitions/entity_id_w_dist'
    example: [ ["123", 0.9], ["456", 0.8], ["789", 0.1]]


  query_payload:
    required: ['id', 'k']
    properties:
      id:
        $ref: '#/definitions/entity_id'
      k:
        description: number of neighbors to get
        type: integer
        example: 5
      search_k:
        description: (UNUSED) number of nodes to inspect (leave as -1 if unsure)
        type: integer
        example: -1

  ann_summary:
    properties:
      path_tar:
        type: string
        example: 'my-bucket/ann/INDEX-0.tar.gz'
      ann_meta:
        properties:
          vec_src:
            type: string
            example: 'dynamoDB:repr-table'
          metric:
            type: string
            example: 'angular'
          n_dim:
            type: integer
            example: 1024
          timestamp_utc:
            type: string
            example: '2019-04-16T03:21:17.040380'
      ts_read:
        type: integer
        example: '2019-04-16T14:40:39+00:00'
      n_ids:
        type: integer
        example: 5906
      head5_ids:
        $ref: '#/definitions/entity_ids'