createEdge

When the payload provided by the server is a node, it creates an edge for a specific connection using that node.

Reference from Relay Docs

You can see that the third argument is a node.

type CreateTodoPayload {
	todo: TodoNode!
}

type Mutation {
	createTodo(input: CreateTodoInput!): CreateTodoPayload!
}

Relay cache updater example:

const serverTodo = store.getRootField('createTodo').getLinkedRecord('todo')
const todoEdges = todosConnection?.getLinkedRecords('edges')

const newTodoEdge = ConnectionHandler.createEdge(
    store,
    todosConnection,
    serverTodo, // node type
    'TodoEdge',
  )

buildConnectionEdge

When the payload provided by the server is a Connection, it creates an edge for a specific connection using that edge.

Reference from Relay Docs

You can see that the third argument is an edge.

type TodoConnection implements Connection {
  edges: [TodoEdge!]!
  pageInfo: PageInfo!
  count: Int
}

type Mutation {
	createTodo(input: CreateTodoInput!): TodoConnection!
}

Relay cache updater example:

const serverEdges = store.getRootField('createTodo').getLinkedRecords('edges')

const newEdge = ConnectionHandler.buildConnectionEdge(store, connection, serverEdge)

if (!newEdge) {
	return
}

ConnectionHandler.insertEdgeAfter(connection, newEdge)

Conclusion

• To create a connection edge from a node, use createEdge.
• To create an edge from an edge provided by a Connection, use buildConnectionEdge.

Use them according to their intended purpose.