BigQuery table insert documentation is incorrect and insufficient #2149

Environment details

• OS: OS X El Capitan
• Node.js version: 6.9.x
• npm version: 3.10.9
• google-cloud-node version: 0.49

Issues

• Incorrect Promise API array indexes in documentation
• Incomplete table.insert PartialFailureError handling example in Promise API documentation

Steps to reproduce

1. Follow documentation here and write the following code:

    this.table.insert(rows, { raw: false }).then((data) => {
      let insertErrors = data[0];
      let apiResponse = data[1];
    }

2. Debug the code and notice that the API Response is in data[0] and that the insertion errors are in data[1]. This is the opposite of what the docs state.

The code makes sense because I don't want to be checking for the apiResponse in index 0 on success and index 1 on failure. 'apiResponse should be in index 0 as it is now and then index 1 will be empty or have the insertion errors if they exist. So this seems to be a docs issue rather than a code issue.

My working code is similar to this:

    this.table.insert(item, { raw: false }).then((data) => {
      let insertErrors = data[1];

      if (insertErrors) {
        logger.info(`insertErrors: ${JSON.stringify(insertErrors)}`);
        // Some rows failed to insert, while others may have succeeded.
        insertErrors.map((insertError) => {
          insertError.errors.map((error) => {
            logger.error(`PartialFailureError: BigQuery insert failed due to: ${JSON.stringify(error)}`);
          });
        });
      }
      return message;
    }).catch((error) => {
      throw new Error(`Error inserting into bigQuery for id: "${item.id}": ${JSON.stringify(error)}`);
    });

3. Now the callback docs for table.insert mention that you can do something like if (err.name === 'PartialFailureError') but using the Promise API, I never get back any objects with a name field. The apiResponse is of this format:

  "kind": "bigquery#tableDataInsertAllResponse",

And the insertErrors object is of this format:

  [
    {
      "index": 1,
      "errors": [
        {
          "reason": "invalid",
          "location": "name",
          "debugInfo": "generic::invalid_argument: Conversion from int64 to string is unsupported.",
          "message": "Conversion from int64 to string is unsupported."
        }
      ]
    },
    {
      "index": 0,
      "errors": [
        {
          "reason": "stopped"
        }
      ]
    }
  ]

So it's unclear why the docs indicate that you should check against the err.name field.

At minimum, if there is a significant difference for handling the response from the Promise API, then that needs to be documented but currently the docs for using the table.insert Promise API are bare bones and incomplete.

From this comment it looks like the tests are only written against the callback API and not the Promise API.