[Feedback]New docs are very hard to navigate

[cjsedwards]

Page: /start/q/integration/android

Feedback:

I am finding it much more difficult to find useful information in the new docs. Is it possible to put a link back to the old format?

[swaminator]

@cjsedwards what specifically are you finding hard?

[cjsedwards]

Almost everything. The search is very poor. It only gives you a few results, and if it isn't in those results, I have to manually walk through the docs page by page. Previously I could just use the browser's built-in find to find what I need.

Things I've been trying to look up lately:

1. How to create a query from a global secondary index (still haven't found this)
2. Combining authorization methods
3. Accessing the API from a lambda

[swaminator]

@cjsedwards The v1 docs are archived on a GitHub branch here: https://github.com/aws-amplify/docs/tree/gh-pages. You can use that to search through the content - I will also provide you with links to the content you're looking for in the new docs.

Your feedback on the search not being good enough is very much on point. We are actively working on improving the search so you can find content more easily. What will help us is if you can tell us the steps you took to find the same content on the v1 docs I shared.

[cjsedwards]

For a surprisingly large number of searches, I would go to the page title "GraphQL Transform", and search keywords.
So in the example of #1 above, I just went into graphql.md in the github repo you provided, searched for "secondary" using Chrome's Find in Page, and found this snippet: (edit, musn't have been secondary I searched on, probably @key because I knew that was related, or possibly just index)

This @key above allows us to efficiently query Order objects by both a customerEmail and the createdAt time stamp. The @key above creates a DynamoDB table where the primary index's hash key is customerEmail and the sort key is createdAt. This allows us to write queries like this:

query ListOrdersForCustomerIn2019 {
  listOrders(customerEmail:"me@email.com", createdAt: { beginsWith: "2019" }) {
    items {
      orderId
      customerEmail
      createdAt
    }
  }
}

The query above shows how we can use compound key structures to implement more powerful query patterns on top of DynamoDB but we are not quite done yet. Given that DynamoDB limits you to query by at most two attributes at a time, the @key directive helps by streamlining the process of creating composite sort keys such that you can support querying by more than two attributes at a time. For example, we can implement “Get items by order, status, and createdAt” as well as “Get items by status and createdAt” for a single @model with this schema.

type Item @model
  @key(fields: ["orderId", "status", "createdAt"])
  @key(name: "ByStatus", fields: ["status", "createdAt"], queryField: "itemsByStatus") {
  orderId: ID!
  status: Status!
  createdAt: AWSDateTime!
  name: String!
}
enum Status {
  DELIVERED
  IN_TRANSIT
  PENDING
  UNKNOWN
}

The primary @key with 3 fields performs a bit more magic than the 1 and 2 field variants. The first field orderId will be the HASH key as expected, but the SORT key will be a new composite key named status#createdAt that is made of the status and createdAt fields on the @model. The @key directive creates the table structures and also generates resolvers that inject composite key values for you during queries and mutations.

Using this schema, you can query the primary index to get IN_TRANSIT items created in 2019 for a given order.

# Get items for order by status by createdAt.
query ListInTransitItemsForOrder {
  listItems(orderId:"order1", statusCreatedAt: { beginsWith: { status: IN_TRANSIT, createdAt: "2019" }}) {
    items {
      orderId
      status
      createdAt
      name
    }
  }
}

[cjsedwards]

For #2 (Combining authorization methods) it took me quite a while to figure out I had to include "authMode: 'API_KEY'" when using the API.graphql if my authorization method differed from the default authorization method.

I cannot remember the place I finally figured out that I needed that.

[cjsedwards]

For # 3 (accessing api from lambda), I did eventually figure out to use this through a google search:
https://docs.amplify.aws/cli/function#set-up-a-function

Another thing I couldn't find on the docs recently is that I can retrieve the calling user's cognito id from the event args through event.identity.sub so that I can do additional authorization checks

[cjsedwards]

Ok for #1, I'm still stuck. Using the list approach above doesn't seem to actually use the GSI, the way I know this is when I run it using the appSync console, and I limit it to 1 result, it won't give me the result (I have to use nextToken repeatedly to get the item).

If you can point me how to have it create a getItemBySecondaryIndex type query that returns me a single result, that would be grand, thanks!

[cjsedwards]

Figured out from this blog post:
https://medium.com/swlh/how-to-create-secondary-indexes-with-aws-appsync-7830c11bc17d

I was missing the "queryField" attribute passed into @key

[cjsedwards]

@swaminator New docs issue, I'm trying to hunt down a solution for this issue:
aws-amplify/amplify-cli#808

There is a link to your docs in this issue but it is now a broken link:
https://aws-amplify.github.io/docs/cli/graphql#apikeyexpirationepoch

[cjsedwards]

Once again, the docs search provides no help on this issue.

[mauerbac]

Hey @cjsedwards - I've added this issue to a larger Epic around improving search #1911. I also see the issue you linked was closed. For clarity, if you have other questions or feedback can you open a new issue? We also have a new Discord Server to get feedback in realtime.