Table of Contents - ArangoDB · 2018. 1. 26. · ArangoDB v3.3.3 HTTP API Documentation Welcome to...

1.10.1

1.10.2

1.16.1

1.16.2

1.16.3

1.16.4

1.17.1

1.17.2

1.17.3

1.17.4

1.17.5

TableofContentsIntroduction

GeneralHTTPHandling

HTTPInterface

Databases

To-Endpoint

Management

NotesonDatabases

Collections

Creating

GettingInformation

Modifying

Documents

BasicsandTerminology

WorkingwithDocuments

AddressandEtag

WorkingwithEdges

GeneralGraph

Management

Vertices

Traversals

AQLQueryCursors

QueryResults

AccessingCursors

AQLQueries

AQLQueryCache

AQLUserFunctionsManagement

SimpleQueries

AsyncResultHandling

BulkImport/Export

JSONDocuments

Headers&Values

BatchRequests

Exportingdata

Indexes

WorkingwithIndexes

Skiplist

Persistent

1.17.6

1.19.1

1.19.2

1.19.3

1.19.4

1.23.1

1.23.2

1.23.3

Fulltext

Transactions

Replication

ReplicationDump

ReplicationLogger

ReplicationApplier

OtherReplicationCommands

Sharding

Monitoring

Endpoints

FoxxServices

Management

Configuration

Miscellaneous

UserManagement

Agency

Miscellaneousfunctions

ArangoDBv3.3.3HTTPAPIDocumentationWelcometotheArangoDBHTTPAPIdocumentation!ThisdocumentationisforAPIdevelopers.AsauseroradministratorofArangoDByoushouldnotneedtheinformationprovidedherein.

Ingeneral,asauserofArangoDByouwilluseoneofthelanguagedrivers.

Introduction

GeneralHTTPRequestHandlinginArangoDB

Protocol

ArangoDBexposesitsAPIviaHTTP,makingtheserveraccessibleeasilywithavarietyofclientsandtools(e.g.browsers,curl,telnet).ThecommunicationcanoptionallybeSSL-encrypted.

ArangoDBusesthestandardHTTPmethods(e.g.GET,POST,PUT,DELETE)plusthePATCHmethoddescribedinRFC5789.

MostserverAPIsexpectclientstosendanypayloaddatainJSONformat.DetailsontheexpectedformatandJSONattributescanbefoundinthedocumentationoftheindividualservermethods.

ClientssendingrequeststoArangoDBmustuseeitherHTTP1.0orHTTP1.1.OtherHTTPversionsarenotsupportedbyArangoDBandanyattempttosendadifferentHTTPversionsignaturewillresultintheserverrespondingwithanHTTP505(HTTPversionnotsupported)error.

ArangoDBwillalwaysrespondtoclientrequestswithHTTP1.1.ClientsshouldthereforesupportHTTPversion1.1.

ClientsarerequiredtoincludetheContent-LengthHTTPheaderwiththecorrectcontentlengthineveryrequestthatcanhaveabody(e.g.POST,PUTorPATCH)request.ArangoDBwillnotprocessrequestswithoutaContent-Lengthheader-thuschunkedtransferencodingforPOST-documentsisnotsupported.

HTTPKeep-Alive

ArangoDBsupportsHTTPkeep-alive.IftheclientdoesnotsendaConnectionheaderinitsrequest,andtheclientusesHTTPversion1.1,ArangoDBwillassumetheclientwantstokeepalivetheconnection.Ifclientsdonotwishtousethekeep-alivefeature,theyshouldexplicitlyindicatethatbysendingaConnection:CloseHTTPheaderintherequest.

ArangoDBwillcloseconnectionsautomaticallyforclientsthatsendrequestsusingHTTP1.0,exceptiftheysendanConnection:Keep-Aliveheader.

ThedefaultKeep-Alivetimeoutcanbespecifiedatserverstartusingthe--http.keep-alive-timeoutparameter.

EstablishingTCPconnectionsisexpensive,sinceittakesseveralpingpongsbetweenthecommunicationparties.ThereforeyoucanuseconnectionkeepalivetosendseveralHTTPrequestoveroneTCP-connection;Eachrequestistreatedindependentlybydefinition.Youcanusethisfeaturetobuildupasocalledconnectionpoolwithseveralestablishedconnectionsinyourclientapplication,anddynamicallyre-useoneofthosethenidleconnectionsforsubsequentrequests.

Blockingvs.Non-blockingHTTPRequests

ArangoDBsupportsbothblockingandnon-blockingHTTPrequests.

ArangoDBisamulti-threadedserver,allowingtheprocessingofmultipleclientrequestsatthesametime.Request/responsehandlingandtheactualworkareperformedontheserverinparallelbymultipleworkerthreads.

Still,clientsneedtowaitfortheirrequeststobeprocessedbytheserver,andthuskeeponeconnectionofapooloccupied.Bydefault,theserverwillfullyprocessanincomingrequestandthenreturntheresulttotheclientwhentheoperationisfinished.Theclientmustwaitfortheserver'sHTTPresponsebeforeitcansendadditionalrequestsoverthesameconnection.Forclientsthataresingle-threadedand/orareblockingonI/Othemselves,waitingidlefortheserverresponsemaybenon-optimal.

Toreduceblockingontheclientside,ArangoDBoffersagenericmechanismfornon-blocking,asynchronousexecution:clientscanaddtheHTTPheaderx-arango-async:truetoanyoftheirrequests,markingthemastobeexecutedasynchronouslyontheserver.ArangoDBwillputsuchrequestsintoanin-memorytaskqueueandreturnanHTTP202(accepted)responsetotheclientinstantlyandthusfinishthisHTTP-request.Theserverwillexecutethetasksfromthequeueasynchronouslyasfastaspossible,whileclientscancontinuetodootherwork.Iftheserverqueueisfull(i.e.containsasmanytasksasspecifiedbytheoption"--scheduler.maximal-queue-size"),thentherequestwillberejectedinstantlywithanHTTP500(internalservererror)response.

GeneralHTTPHandling

Asynchronousexecutiondecouplestherequest/responsehandlingfromtheactualworktobeperformed,allowingfastserverresponsesandgreatlyreducingwaittimeforclients.Overallthisallowsformuchhigherthroughputthanifclientswouldalwayswaitfortheserver'sresponse.

Keepinmindthattheasynchronousexecutionisjust"fireandforget".ClientswillgetanyoftheirasynchronousrequestsansweredwithagenericHTTP202response.Atthetimetheserversendsthisresponse,itdoesnotknowwhethertherequestedoperationcanbecarriedoutsuccessfully(theactualoperationexecutionwillhappenatsomelaterpoint).Clientsthereforecannotmakeadecisionbasedontheserverresponseandmustrelyontheirrequestsbeingvalidandprocessablebytheserver.

Additionally,theserver'sasynchronoustaskqueueisanin-memorydatastructure,meaningnot-yetprocessedtasksfromthequeuemightbelostincaseofacrash.Clientsshouldthereforenotusetheasynchronousfeaturewhentheyhavestrictdurabilityrequirementsoriftheyrelyontheimmediateresultoftherequesttheysend.

FordetailsonthesubsequentprocessingreadonunderAsyncResulthandling.

Authentication

ClientauthenticationcanbeachievedbyusingtheAuthorizationHTTPheaderinclientrequests.ArangoDBsupportsauthenticationviaHTTPBasicorJWT.

AuthenticationisturnedonbydefaultforallinternaldatabaseAPIsbutturnedoffforcustomFoxxapps.TotoggleauthenticationforincomingrequeststotheinternaldatabaseAPIs,usetheoption--server.authentication.ThisoptionisturnedonbydefaultsoauthenticationisrequiredforthedatabaseAPIs.

PleasenotethatrequestsusingtheHTTPOPTIONSmethodwillbeansweredbyArangoDBinanycase,evenifnoauthenticationdataissentbytheclientoriftheauthenticationdataiswrong.ThisisrequiredforhandlingCORSpreflightrequests(seeCrossOriginResourceSharingrequests).TheresponsetoanHTTPOPTIONSrequestwillbegenericandnotexposeanyprivatedata.

ThereisanadditionaloptiontocontrolauthenticationforcustomFoxxapps.Theoption--server.authentication-system-onlycontrolswhetherauthenticationisrequiredonlyforrequeststotheinternaldatabaseAPIsandtheadmininterface.Itisturnedonbydefault,meaningthatotherAPIs(thisincludescustomFoxxapps)donotrequireauthentication.

ThedefaultvaluesallowexposingapubliccustomFoxxAPIbuiltwithArangoDBtotheoutsideworldwithouttheneedforHTTPauthentication,butstillprotectingtheusageoftheinternaldatabaseAPIs(i.e./_api/,/_admin/)withHTTPauthentication.

Iftheserverisstartedwiththe--server.authentication-system-onlyoptionsettofalse,allincomingrequestswillneedHTTPauthenticationiftheserverisconfiguredtorequireHTTPauthentication(i.e.--server.authenticationtrue).SettingtheoptiontotruewillmaketheserverrequireauthenticationonlyforrequeststotheinternaldatabaseAPIsandwillallowunauthenticatedrequeststoallotherURLs.

Here'sashortsummary:

--server.authenticationtrue--server.authentication-system-onlytrue:thiswillrequireauthenticationforallrequeststotheinternaldatabaseAPIsbutnotcustomFoxxapps.Thisisthedefaultsetting.--server.authenticationtrue--server.authentication-system-onlyfalse:thiswillrequireauthenticationforallrequests(includingcustomFoxxapps).--server.authenticationfalse:authenticationdisabledforallrequests

Wheneverauthenticationisrequiredandtheclienthasnotyetauthenticated,ArangoDBwillreturnHTTP401(Unauthorized).ItwillalsosendtheWWW-Authenticateresponseheader,indicatingthattheclientshouldprompttheuserforusernameandpasswordifsupported.Iftheclientisabrowser,thensendingbackthisheaderwillnormallytriggerthedisplayofthebrowser-sideHTTPauthenticationdialog.AsshowingthebrowserHTTPauthenticationdialogisundesiredinAJAXrequests,ArangoDBcanbetoldtonotsendtheWWW-Authenticateheaderbacktotheclient.WheneveraclientsendstheX-Omit-WWW-AuthenticateHTTPheader(withanarbitraryvalue)toArangoDB,ArangoDBwillonlysendstatuscode401,butnoWWW-Authenticateheader.Thisallowsclientstoimplementcredentialshandlingandbypassingthebrowser'sbuilt-indialog.

AuthenticationviaJWT

ToauthenticateviaJWTyoumustfirstobtainaJWT.TodososendaPOSTrequestto

/_open/auth

GeneralHTTPHandling

containingusernameandpasswordJSON-encodedlikeso:

{"username":"root","password":"rootPassword"}

Uponsuccesstheendpointwillreturna200OKandananswercontainingtheJWTinaJSON-encodedobjectlikeso:

{"jwt":"eyJhbGciOiJIUzI1NiI..x6EfI"}

ThisJWTshouldthenbeusedwithintheAuthorizationHTTPheaderinsubsequentrequests:

Authorization:bearereyJhbGciOiJIUzI1NiI..x6EfI

PleasenotethattheJWTwillexpireafter1monthandneedstobeupdated.

ArangoDBusesastandardJWTauthentication.Thesecretmayeitherbesetusing--server.jwt-secretorwillberandomlygenerateduponserverstartup.

FormoreinformationonJWTpleaseconsultRFC7519andhttps://jwt.io

ErrorHandling

ThefollowingshouldbenotedabouthowArangoDBhandlesclienterrorsinitsHTTPlayer:

clientrequestsusinganHTTPversionsignaturedifferentthanHTTP/1.0orHTTP/1.1willgetanHTTP505(HTTPversionnotsupported)errorinreturn.ArangoDBwillrejectclientrequestswithanegativevalueintheContent-LengthrequestheaderwithHTTP411(LengthRequired).Arangodbdoesn'tsupportPOSTwithtransfer-encoding:chunkedwhichforbidstheContent-Lengthheaderabove.themaximumURLlengthacceptedbyArangoDBis16K.IncomingrequestswithlongerURLswillberejectedwithanHTTP414(Request-URItoolong)error.iftheclientsendsaContent-Lengthheaderwithavaluebiggerthan0foranHTTPGET,HEAD,orDELETErequest,ArangoDBwillprocesstherequest,butwillwriteawarningtoitslogfile.whentheclientsendsaContent-Lengthheaderthathasavaluethatislowerthantheactualsizeofthebodysent,ArangoDBwillrespondwithHTTP400(BadRequest).ifclientssendaContent-Lengthvaluebiggerthantheactualsizeofthebodyoftherequest,ArangoDBwillwaitforabout90secondsfortheclienttocompleteitsrequest.Iftheclientdoesnotsendtheremainingbodydatawithinthistime,ArangoDBwillclosetheconnection.Clientsshouldavoidsendingsuchmalformedrequestsasthiswillblockonetcpconnection,andmayleadtoatemporaryfiledescriptorleak.whenclientssendabodyoraContent-Lengthvaluebiggerthanthemaximumallowedvalue(512MB),ArangoDBwillrespondwithHTTP413(RequestEntityTooLarge).iftheoveralllengthoftheHTTPheadersaclientsendsforonerequestexceedsthemaximumallowedsize(1MB),theserverwillfailwithHTTP431(RequestHeaderFieldsTooLarge).ifclientsrequestanHTTPmethodthatisnotsupportedbytheserver,ArangoDBwillreturnwithHTTP405(MethodNotAllowed).ArangoDBoffersgeneralsupportforthefollowingHTTPmethods:

GETPOSTPUTDELETEHEADPATCHOPTIONS

PleasenotethatnotallserveractionsallowusingalloftheseHTTPmethods.Youshouldlookupupthesupportedmethodsforeachmethodyouintendtouseinthemanual.

RequestsusinganyotherHTTPmethod(suchasforexampleCONNECT,TRACEetc.)willberejectedbyArangoDBasmentionedbefore.

Cross-OriginResourceSharing(CORS)requests

GeneralHTTPHandling

ArangoDBwillautomaticallyhandleCORSrequestsasfollows:

Preflight

Whenabrowseristoldtomakeacross-originrequestthatincludesexplicitheaders,credentialsorusesHTTPmethodsotherthanGETorPOST,itwillfirstperformaso-calledpreflightrequestusingtheOPTIONSmethod.

ArangoDBwillrespondtoOPTIONSrequestswithanHTTP200statusresponsewithanemptybody.Sincepreflightrequestsarenotexpectedtoincludeorevenindicatethepresenceofauthenticationcredentialsevenwhentheywillbepresentintheactualrequest,ArangoDBdoesnotenforceauthenticationforOPTIONSrequestsevenwhenauthenticationisenabled.

ArangoDBwillsetthefollowingheadersintheresponse:

access-control-allow-credentials:willbesettofalsebydefault.Fordetailsonwhenitwillbesettotrueseethenextsectiononcookies.

access-control-allow-headers:willbesettotheexectvalueoftherequest'saccess-control-request-headersheaderoromittedifnosuchheaderwassentintherequest.

access-control-allow-methods:willbesettoalistofallsupportedHTTPheadersregardlessofthetargetendpoint.Inotherwordsthatamethodislistedinthisheaderdoesnotguaranteethatitwillbesupportedbytheendpointintheactualrequest.

access-control-allow-origin:willbesettotheexactvalueoftherequest'soriginheader.

access-control-expose-headers:willbesettoalistofresponseheadersusedbytheArangoDBHTTPAPI.

access-control-max-age:willbesettoanimplementation-specifcvalue.

Actualrequest

IfarequestusinganyotherHTTPmethodthanOPTIONSincludesanoriginheader,ArangoDBwilladdthefollowingheaderstotheresponse:

access-control-allow-credentials:willbesettofalsebydefault.Fordetailsonwhenitwillbesettotrueseethenextsectiononcookies.

access-control-allow-origin:willbesettotheexactvalueoftherequest'soriginheader.

access-control-expose-headers:willbesettoalistofresponseheadersusedbytheArangoDBHTTPAPI.

WhenmakingCORSrequeststoendpointsofFoxxservices,thevalueoftheaccess-control-expose-headersheaderwillinsteadbesettoalistofresponseheadersusedintheresponseitself(butnotincludingtheaccess-control-headers).NotethatFoxxservicesmayoverridethisbehaviour.

Cookiesandauthentication

Inorderfortheclienttobeallowedtocorrectlyprovideauthenticationcredentialsorhandlecookies,ArangoDBneedstosettheaccess-control-allow-credentialsresponseheadertotrueinsteadoffalse.

ArangoDBwillautomaticallysetthisheadertotrueifthevalueoftherequest'soriginheadermatchesatrustedorigininthehttp.trusted-originconfigurationoption.TomakeArangoDBtrustacertainorigin,youcanprovideastartupoptionwhenrunningarangodlikethis:

--http.trusted-origin"http://localhost:8529"

Tospecifymultipletrustedorigins,theoptioncanbespecifiedmultipletimes.Alternativelyyoucanusethespecialvalue"*"totrustanyorigin:

--http.trusted-origin"*"

Notethatbrowserswillnotactuallyincludecredentialsorcookiesincross-originrequestsunlessexplicitlytoldtodoso:

WhenusingtheFetchAPIyouneedtosetthecredentialsoptiontoinclude.

fetch("./",{credentials:"include"}).then(/*…*/)

GeneralHTTPHandling

WhenusingXMLHttpRequestyouneedtosetthewithCredentialsoptiontotrue.

varxhr=newXMLHttpRequest();

xhr.open('GET','https://example.com/',true);

xhr.withCredentials=true;

xhr.send(null);

WhenusingjQueryyouneedtosetthexhrFieldsoption:

$.ajax({

url:'https://example.com',

xhrFields:{

withCredentials:true

HTTPmethodoverridingArangoDBprovidesastartupoption--http.allow-method-override.ThisoptioncanbesettoallowoverridingtheHTTPrequestmethod(e.g.GET,POST,PUT,DELETE,PATCH)ofarequestusingoneofthefollowingcustomHTTPheaders:

x-http-method-overridex-http-methodx-method-override

ThisallowsusingHTTPclientsthatdonotsupportall"common"HTTPmethodssuchasPUT,PATCHandDELETE.Italsoallowsbypassingproxiesandtoolsthatwouldotherwisejustletcertaintypesofrequests(e.g.GETandPOST)passthrough.

Enablingthisoptionmayimposeasecurityrisk,soitshouldonlybeusedinverycontrolledenvironments.Thusthedefaultvalueforthisoptionisfalse(nomethodoverridingallowed).Youneedtoenableitexplicitlyifyouwanttousethisfeature.

GeneralHTTPHandling

HTTPInterfaceFollowingyouhaveArangoDB'sHTTPInterfaceforDocuments,Databases,Edgesandmore.

TherearealsosomeexamplesprovidedforeveryAPIaction.

YoumayalsousetheinteractiveSwaggerdocumentationintheArangoDBwebinterfacetoexploretheAPIcallsbelow.

HTTPInterface

HTTPInterfaceforDatabases

AddressofaDatabase

AnyoperationtriggeredviaArangoDB'sHTTPRESTAPIisexecutedinthecontextofexactlyonedatabase.Toexplicitlyspecifythedatabaseinarequest,therequestURImustcontainthedatabasenameinfrontoftheactualpath:

http://localhost:8529/_db/mydb/...

where...istheactualpathtotheaccessedresource.Intheexample,theresourcewillbeaccessedinthecontextofthedatabasemydb.ActualURLsinthecontextofmydbcouldlooklikethis:

http://localhost:8529/_db/mydb/_api/version

http://localhost:8529/_db/mydb/_api/document/test/12345

http://localhost:8529/_db/mydb/myapp/get

Databases

Database-to-EndpointMappingIfadatabasenameispresentintheURIasabove,ArangoDBwillconsultthedatabase-to-endpointmappingforthecurrentendpoint,andvalidateifaccesstothedatabaseisallowedontheendpoint.Iftheendpointisnotrestrictedtoanarrayofdatabases,ArangoDBwillcontinuewiththeregularauthenticationprocedure.Iftheendpointisrestrictedtoanarrayofspecifieddatabases,ArangoDBwillcheckiftherequesteddatabaseisinthearray.Ifnot,therequestwillbeturneddowninstantly.Ifyes,thenArangoDBwillcontinuewiththeregularauthenticationprocedure.

IftherequestURIwashttp://localhost:8529/_db/mydb/...,thentherequesttomydbwillbeallowed(ordisallowed)inthefollowingsituations:

Endpoint-to-databasemappingAccessto*mydb*allowed?

-----------------------------------------------------

["_system"]no

["_system","mydb"]yes

["mydb"]yes

["mydb","_system"]yes

["test1","test2"]no

IncasenodatabasenameisspecifiedintherequestURI,ArangoDBwillderivethedatabasenamefromtheendpoint-to-databasemappingoftheendpointtheconnectionwascominginon.

Iftheendpointisnotrestrictedtoanarrayofdatabases,ArangoDBwillassumethe_systemdatabase.Iftheendpointisrestrictedtooneormultipledatabases,ArangoDBwillassumethefirstnamefromthearray.

Followingisanoverviewofwhichdatabasenamewillbeassumedfordifferentendpoint-to-databasemappingsincasenodatabasenameisspecifiedintheURI:

Endpoint-to-databasemappingDatabase

------------------------------------

[]_system

["_system"]_system

["_system","mydb"]_system

["mydb"]mydb

["mydb","_system"]mydb

To-Endpoint

DatabaseManagementThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingdatabases.

TheHTTPinterfacefordatabasesprovidesoperationstocreateanddropindividualdatabases.ThesearemappedtothestandardHTTPmethodsPOSTandDELETE.ThereisalsotheGETmethodtoretrieveanarrayofexistingdatabases.

Pleasenotethatalldatabasemanagementoperationscanonlybeaccessedviathedefaultdatabase(_system)andnoneoftheotherdatabases.

ManagingDatabasesusingHTTP

Informationofthedatabase

retrievesinformationaboutthecurrentdatabase

GET/_api/database/current

Retrievesinformationaboutthecurrentdatabase

TheresponseisaJSONobjectwiththefollowingattributes:

name:thenameofthecurrentdatabase

id:theidofthecurrentdatabase

path:thefilesystempathofthecurrentdatabase

isSystem:whetherornotthecurrentdatabaseisthe_systemdatabase

Example:

shell>curl--dump-http://localhost:8529/_api/database/current

HTTP/1.1200OK

content-type:application/json;charset=utf-8

x-content-type-options:nosniff

"error":false,

"code":200,

"result":{

"name":"_system",

"id":"1",

"path":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/databases/database-1",

"isSystem":true

ReturnCodes

200:isreturnediftheinformationwasretrievedsuccessfully.400:isreturnediftherequestisinvalid.404:isreturnedifthedatabasecouldnotbefound.

Examples

shell>curl--dump-http://localhost:8529/_api/database/current

HTTP/1.1200OK

Management

showresponsebody

Listofaccessibledatabases

retrievesalistofalldatabasesthecurrentusercanaccess

GET/_api/database/user

Retrievesthelistofalldatabasesthecurrentusercanaccesswithoutspecifyingadifferentusernameorpassword.

Example:

shell>curl--dump-http://localhost:8529/_api/database/user

HTTP/1.1200OK

"error":false,

"code":200,

"result":[

"_system"

ReturnCodes

200:isreturnedifthelistofdatabasewascompiledsuccessfully.400:isreturnediftherequestisinvalid.

Examples

shell>curl--dump-http://localhost:8529/_api/database/user

HTTP/1.1200OK

showresponsebody

Listofdatabases

retrievesalistofallexistingdatabases

GET/_api/database

Retrievesthelistofallexistingdatabases

Note:retrievingthelistofdatabasesisonlypossiblefromwithinthe_systemdatabase.

Note:YoushouldusetheGETuserAPItofetchthelistoftheavailabledatabasesnow.

Example:

shell>curl--dump-http://localhost:8529/_api/database

Management

HTTP/1.1200OK

"error":false,

"code":200,

"result":[

"_system"

ReturnCodes

200:isreturnedifthelistofdatabasewascompiledsuccessfully.400:isreturnediftherequestisinvalid.403:isreturnediftherequestwasnotexecutedinthe_systemdatabase.

Examples

shell>curl--dump-http://localhost:8529/_api/database

HTTP/1.1200OK

showresponsebody

Createdatabase

createsanewdatabase

POST/_api/database

AJSONobjectwiththesepropertiesisrequired:

name:Hastocontainavaliddatabasename.users:Hastobeanarrayofuserobjectstoinitiallycreateforthenewdatabase.Userinformationwillnotbechangedforusersthatalreadyexist.Ifusersisnotspecifiedordoesnotcontainanyusers,adefaultuserrootwillbecreatedwithanemptystringpassword.Thisensuresthatthenewdatabasewillbeaccessibleafteritiscreated.Eachuserobjectcancontainthefollowingattributes:

username:Loginnameoftheusertobecreatedpasswd:Theuserpasswordasastring.Ifnotspecified,itwilldefaulttoanemptystring.active:Aflagindicatingwhethertheuseraccountshouldbeactivatedornot.Thedefaultvalueistrue.Ifsettofalse,theuserwon'tbeabletologintothedatabase.extra:AJSONobjectwithextrauserinformation.ThedatacontainedinextrawillbestoredfortheuserbutnotbeinterpretedfurtherbyArangoDB.

Createsanewdatabase

TheresponseisaJSONobjectwiththeattributeresultsettotrue.

Note:creatinganewdatabaseisonlypossiblefromwithinthe_systemdatabase.

Example:Creatingadatabasenamedexample.

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/database<<EOF

"name":"example"

Management

HTTP/1.1201Created

"error":false,

"code":201,

"result":true

Example:Creatingadatabasenamedmydbwithtwousers.

"name":"mydb",

"users":[

"username":"admin",

"passwd":"secret",

"active":true

"username":"tester",

"passwd":"test001",

"active":false

HTTP/1.1201Created

"error":false,

"code":201,

"result":true

"name":"example"

HTTP/1.1201Created

showresponsebodyCreatingadatabasenamedmydbwithtwousers.

"name":"mydb",

"users":[

Management

"username":"admin",

"passwd":"secret",

"active":true

"username":"tester",

"passwd":"test001",

"active":false

HTTP/1.1201Created

showresponsebody

Dropdatabase

dropanexistingdatabase

DELETE/_api/database/{database-name}

PathParameters

database-name(required):Thenameofthedatabase

Dropsthedatabasealongwithalldatastoredinit.

Note:droppingadatabaseisonlypossiblefromwithinthe_systemdatabase.The_systemdatabaseitselfcannotbedropped.

Example:

shell>curl-XDELETE--dump-http://localhost:8529/_api/database/example

HTTP/1.1200OK

"error":false,

"code":200,

"result":true

ReturnCodes

200:isreturnedifthedatabasewasdroppedsuccessfully.400:isreturnediftherequestismalformed.403:isreturnediftherequestwasnotexecutedinthe_systemdatabase.404:isreturnedifthedatabasecouldnotbefound.

Examples

shell>curl-XDELETE--dump-http://localhost:8529/_api/database/example

HTTP/1.1200OK

Management

showresponsebody

Management

NotesonDatabasesPleasekeepinmindthateachdatabasecontainsitsownsystemcollections,whichneedtosetupwhenadatabaseiscreated.Thiswillmakethecreationofadatabasetakeawhile.Replicationisconfiguredonaper-databaselevel,meaningthatanyreplicationloggingorapplyingfortheanewdatabasemustbeconfiguredexplicitlyafteranewdatabasehasbeencreated.Foxxapplicationsarealsoavailableonlyinthecontextofthedatabasetheyhavebeeninstalledin.AnewdatabasewillonlyprovideaccesstothesystemapplicationsshippedwithArangoDB(thatisthewebinterfaceatthemoment)andnootherFoxxapplicationsuntiltheyareexplicitlyinstalledfortheparticulardatabase.

Database

ArangoDBcanhandlemultipledatabasesinthesameserverinstance.Databasescanbeusedtologicallygroupandseparatedata.AnArangoDBdatabaseconsistsofcollectionsanddedicateddatabase-specificworkerprocesses.Adatabasecontainsitsowncollections(whichcannotbeaccessedfromotherdatabases),Foxxapplicationsandreplicationloggersandappliers.EachArangoDBdatabasecontainsitsownsystemcollections(e.g._users,_graphs,...).

TherewillalwaysbeatleastonedatabaseinArangoDB.Thisisthedefaultdatabasenamed_system.Thisdatabasecannotbedroppedandprovidesspecialoperationsforcreating,droppingandenumeratingdatabases.Userscancreateadditionaldatabasesandgivethemuniquenamestoaccessthemlater.Databasemanagementoperationscannotbeinitiatedfromoutofuser-defineddatabases.

WhenArangoDBisaccessedviaitsHTTPRESTAPI,thedatabasenameisreadfromthefirstpartoftherequestURIpath(e.g./_db/_system/...).IftherequestURIdoesnotcontainadatabasename,thedatabasenameisautomaticallydeterminedbythealgorithmdescribedinDatabase-to-EndpointMapping.

DatabaseName

AsingleArangoDBinstancecanhandlemultipledatabasesinparallel.Whenmultipledatabasesareused,eachdatabasemustbegivenanuniquename.Thisnameisusedtouniquelyidentifyadatabase.ThedefaultdatabaseinArangoDBisnamedsystem.Thedatabasenameisastringconsistingofonlyletters,digitsandthe(underscore)and-(dash)characters.User-defineddatabasenamesmustalwaysstartwithaletter.Databasenamesarecase-sensitive.

DatabaseOrganization

AsingleArangoDBinstancecanhandlemultipledatabasesinparallel.Bydefault,therewillbeatleastonedatabasewhichisnamed_system.Databasesarephysicallystoredinseparatesub-directoriesunderneaththedatabasedirectory,whichitselfresidesintheinstance'sdatadirectory.

Eachdatabasehasitsownsub-directory,nameddatabase-.Thedatabasedirectorycontainssub-directoriesforthecollectionsofthedatabase,andafilenamedparameter.json.Thisfilecontainsthedatabaseidandname.

InanexampleArangoDBinstancewhichhastwodatabases,thefilesystemlayoutcouldlooklikethis:

data/#theinstance'sdatadirectory

databases/#sub-directorycontainingalldatabases'data

database-<id>/#sub-directoryforasingledatabase

parameter.json#filecontainingdatabaseidandname

collection-<id>/#directorycontainingdataaboutacollection

database-<id>/#sub-directoryforanotherdatabase

parameter.json#filecontainingdatabaseidandname

collection-<id>/#directorycontainingdataaboutacollection

Foxxapplicationsarealsoorganizedindatabase-specificdirectoriesinsidetheapplicationpath.Thefilesystemlayoutcouldlooklikethis:

apps/#theinstance'sapplicationdirectory

system/#systemapplications(canbeignored)

databases/#sub-directorycontainingdatabase-specificapplications

<database-name>/#sub-directoryforasingledatabase

<app-name>#sub-directoryforasingleapplication

NotesonDatabases

<database-name>/#sub-directoryforanotherdatabase

NotesonDatabases

HTTPInterfaceforCollections

Collections

ThisisanintroductiontoArangoDB'sHTTPinterfaceforcollections.

Collection

Acollectionconsistsofdocuments.Itisuniquelyidentifiedbyitscollectionidentifier.Italsohasauniquenamethatclientsshouldusetoidentifyandaccessit.Collectionscanberenamed.Thiswillchangethecollectionname,butnotthecollectionidentifier.Collectionshaveatypethatisspecifiedbytheuserwhenthecollectioniscreated.Therearecurrentlytwotypes:documentandedge.Thedefaulttypeisdocument.

CollectionIdentifier

Acollectionidentifierletsyourefertoacollectioninadatabase.Itisastringvalueandisuniquewithinthedatabase.UptoincludingArangoDB1.1,thecollectionidentifierhasbeenaclient'sprimarymeanstoaccesscollections.StartingwithArangoDB1.2,clientsshouldinsteaduseacollection'suniquenametoaccessacollectioninsteadofitsidentifier.ArangoDBcurrentlyuses64bitunsignedintegervaluestomaintaincollectionidsinternally.Whenreturningcollectionidstoclients,ArangoDBwillputthemintoastringtoensurethecollectionidisnotclippedbyclientsthatdonotsupportbigintegers.ClientsshouldtreatthecollectionidsreturnedbyArangoDBasopaquestringswhentheystoreoruseitlocally.

Note:collectionidshavebeenreturnedasintegersuptoincludingArangoDB1.1

CollectionName

Acollectionnameidentifiesacollectioninadatabase.Itisastringandisuniquewithinthedatabase.Unlikethecollectionidentifieritissuppliedbythecreatorofthecollection.Thecollectionnamemustconsistofletters,digits,andthe_(underscore)and-(dash)charactersonly.PleaserefertoNamingConventionsinArangoDBformoreinformationonvalidcollectionnames.

KeyGenerator

ArangoDBallowsusingkeygeneratorsforeachcollection.Keygeneratorshavethepurposeofauto-generatingvaluesforthe_keyattributeofadocumentifnonewasspecifiedbytheuser.Bydefault,ArangoDBwillusethetraditionalkeygenerator.Thetraditionalkeygeneratorwillauto-generatekeyvaluesthatarestringswithever-increasingnumbers.Theincrementvaluesitusesarenon-deterministic.

Contrary,theautoincrementkeygeneratorwillauto-generatedeterministickeyvalues.Boththestartvalueandtheincrementvaluecanbedefinedwhenthecollectioniscreated.Thedefaultstartvalueis0andthedefaultincrementis1,meaningthekeyvaluesitwillcreatebydefaultare:

1,2,3,4,5,...

Whencreatingacollectionwiththeautoincrementkeygeneratorandanincrementof5,thegeneratedkeyswouldbe:

1,6,11,16,21,...

Theauto-incrementvaluesareincreasedandhandedoutoneachdocumentinsertattempt.Evenifaninsertfails,theauto-incrementvalueisneverrolledback.Thatmeanstheremayexistgapsinthesequenceofassignedauto-incrementvaluesifinsertsfails.

Thebasicoperations(create,read,update,delete)fordocumentsaremappedtothestandardHTTPmethods(POST,GET,PUT,DELETE).

AddressofaCollection

AllcollectionsinArangoDBhaveanuniqueidentifierandauniquename.ArangoDBinternallyusesthecollection'suniqueidentifiertolookupcollections.ThisidentifierhoweverismanagedbyArangoDBandtheuserhasnocontroloverit.Inordertoallowusersusetheirownnames,eachcollectionalsohasauniquename,whichisspecifiedbytheuser.Toaccessacollectionfromtheuserperspective,the

Collections

collectionnameshouldbeused,i.e.:

http://server:port/_api/collection/collection-name

Forexample:Assumethatthecollectionidentifieris7254820andthecollectionnameisdemo,thentheURLofthatcollectionis:

http://localhost:8529/_api/collection/demo

Collections

CreatingandDeletingCollections

Createcollection

createsacollection

POST/_api/collection

journalSize:Themaximalsizeofajournalordatafileinbytes.Thevaluemustbeatleast1048576(1MiB).(Thedefaultisaconfigurationparameter)ThisoptionismeaningfulfortheMMFilesstorageengineonly.replicationFactor:(Thedefaultis1):inacluster,thisattributedetermineshowmanycopiesofeachshardarekeptondifferentDBServers.Thevalue1meansthatonlyonecopy(nosynchronousreplication)iskept.Avalueofkmeansthatk-1replicasarekept.AnytwocopiesresideondifferentDBServers.Replicationbetweenthemissynchronous,thatis,everywriteoperationtothe"leader"copywillbereplicatedtoall"follower"replicas,beforethewriteoperationisreportedsuccessful.Ifaserverfails,thisisdetectedautomaticallyandoneoftheserversholdingcopiestakeover,usuallywithoutanerrorbeingreported.keyOptions:

allowUserKeys:ifsettotrue,thenitisallowedtosupplyownkeyvaluesinthe_keyattributeofadocument.Ifsettofalse,thenthekeygeneratorwillsolelyberesponsibleforgeneratingkeysandsupplyingownkeyvaluesinthe_keyattributeofdocumentsisconsideredanerror.type:specifiesthetypeofthekeygenerator.Thecurrentlyavailablegeneratorsaretraditionalandautoincrement.increment:incrementvalueforautoincrementkeygenerator.Notusedforotherkeygeneratortypes.offset:Initialoffsetvalueforautoincrementkeygenerator.Notusedforotherkeygeneratortypes.

name:Thenameofthecollection.waitForSync:Iftruethenthedataissynchronizedtodiskbeforereturningfromadocumentcreate,update,replaceorremovaloperation.(default:false)doCompact:whetherornotthecollectionwillbecompacted(defaultistrue)ThisoptionismeaningfulfortheMMFilesstorageengineonly.isVolatile:Iftruethenthecollectiondataiskeptin-memoryonlyandnotmadepersistent.Unloadingthecollectionwillcausethecollectiondatatobediscarded.Stoppingorre-startingtheserverwillalsocausefulllossofdatainthecollection.SettingthisoptionwillmaketheresultingcollectionbeslightlyfasterthanregularcollectionsbecauseArangoDBdoesnotenforceanysynchronizationtodiskanddoesnotcalculateanyCRCchecksumsfordatafiles(astherearenodatafiles).Thisoptionshouldthereforebeusedforcache-typecollectionsonly,andnotfordatathatcannotbere-createdotherwise.(Thedefaultisfalse)ThisoptionismeaningfulfortheMMFilesstorageengineonly.shardKeys:(Thedefaultis["_key"]):inacluster,thisattributedetermineswhichdocumentattributesareusedtodeterminethetargetshardfordocuments.Documentsaresenttoshardsbasedonthevaluesoftheirshardkeyattributes.Thevaluesofallshardkeyattributesinadocumentarehashed,andthehashvalueisusedtodeterminethetargetshard.Note:Valuesofshardkeyattributescannotbechangedonceset.Thisoptionismeaninglessinasingleserversetup.numberOfShards:(Thedefaultis1):inacluster,thisvaluedeterminesthenumberofshardstocreateforthecollection.Inasingleserversetup,thisoptionismeaningless.isSystem:Iftrue,createasystemcollection.Inthiscasecollection-nameshouldstartwithanunderscore.Endusersshouldnormallycreatenon-systemcollectionsonly.APIimplementorsmayberequiredtocreatesystemcollectionsinveryspecialoccasions,butnormallyaregularcollectionwilldo.(Thedefaultisfalse)type:(Thedefaultis2):thetypeofthecollectiontocreate.Thefollowingvaluesfortypearevalid:

2:documentcollection3:edgescollection

indexBuckets:Thenumberofbucketsintowhichindexesusingahashtablearesplit.Thedefaultis16andthisnumberhastobeapowerof2andlessthanorequalto1024.Forverylargecollectionsoneshouldincreasethistoavoidlongpauseswhenthehashtablehastobeinitiallybuiltorresized,sincebucketsareresizedindividuallyandcanbeinitiallybuiltinparallel.Forexample,64mightbeasensiblevalueforacollectionwith100000000documents.Currently,onlytheedgeindexrespectsthisvalue,butotherindextypesmightfollowinfutureArangoDBversions.Changes(seebelow)areappliedwhenthecollectionisloadedthenexttime.ThisoptionismeaningfulfortheMMFilesstorageengineonly.distributeShardsLike:(Thedefaultis""):inanenterprisecluster,thisattributebindsthespecificsofshardingforthenewlycreatedcollectiontofollowthatofaspecifiedexistingcollection.Note:Usingthisparameterhasconsequencesfortheprototypecollection.Itcannolongerbedropped,beforeshardingimitatingcollectionsaredropped.Equally,backupsandrestoresofimitating

Creating

collectionsalonewillgeneratewarnings,whichcanbeoverridden,aboutmissingshardingprototype.

Createsanewcollectionwithagivenname.Therequestmustcontainanobjectwiththefollowingattributes.

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/collection<<EOF

"name":"testCollectionBasics"

HTTP/1.1200OK

"code":200,

"error":false,

"status":3,

"statusString":"loaded",

"name":"testCollectionBasics",

"keyOptions":{

"type":"traditional",

"allowUserKeys":true,

"lastValue":0

"type":2,

"indexBuckets":8,

"globallyUniqueId":"h68719E5AC6E7/9999",

"doCompact":true,

"waitForSync":false,

"id":"9999",

"isSystem":false,

"journalSize":33554432,

"isVolatile":false

"name":"testCollectionEdges",

"type":3

HTTP/1.1200OK

"code":200,

"error":false,

"status":3,

"name":"testCollectionEdges",

"keyOptions":{

"lastValue":0

"type":3,

"indexBuckets":8,

"doCompact":true,

"id":"10002",

"isSystem":false,

"isVolatile":false

Creating

Example:

"name":"testCollectionUsers",

"keyOptions":{

"type":"autoincrement",

"increment":5,

"allowUserKeys":true

HTTP/1.1200OK

"code":200,

"error":false,

"status":3,

"keyOptions":{

"offset":0,

"increment":5,

"lastValue":0

"type":2,

"indexBuckets":8,

"doCompact":true,

"id":"10013",

"isSystem":false,

"isVolatile":false

"name":"testCollectionBasics"

HTTP/1.1200OK

showresponsebody

"keyOptions":{

"increment":5,

"allowUserKeys":true

Creating

HTTP/1.1200OK

showresponsebody

Dropsacollection

dropsacollection

DELETE/_api/collection/{collection-name}

PathParameters

collection-name(required):Thenameofthecollectiontodrop.

QueryParameters

isSystem(optional):Whetherornotthecollectiontodropisasystemcollection.Thisparametermustbesettotrueinordertodropasystemcollection.

Dropsthecollectionidentifiedbycollection-name.

Ifthecollectionwassuccessfullydropped,anobjectisreturnedwiththefollowingattributes:

error:false

id:Theidentifierofthedroppedcollection.

Example:Usinganidentifier:

shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/10020

HTTP/1.1200OK

"code":200,

"error":false,

"id":"10020"

Example:Usinganame:

shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/products1

HTTP/1.1200OK

"code":200,

"error":false,

"id":"10027"

Creating

Example:Droppingasystemcollection

shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/_example?isSystem=true

HTTP/1.1200OK

"code":200,

"error":false,

"id":"10034"

ReturnCodes

400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Examples

Usinganidentifier:

shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/10020

HTTP/1.1200OK

showresponsebodyUsinganame:

shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/products1

HTTP/1.1200OK

showresponsebodyDroppingasystemcollection

shell>curl-XDELETE--dump-http://localhost:8529/_api/collection/_example?

isSystem=true

HTTP/1.1200OK

showresponsebody

Truncatecollection

truncatesacollection

Creating

PUT/_api/collection/{collection-name}/truncate

PathParameters

collection-name(required):Thenameofthecollection.

Removesalldocumentsfromthecollection,butleavestheindexesintact.

Example:

shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/truncate

HTTP/1.1200OK

location:/_api/collection/products/truncate

"code":200,

"error":false,

"status":3,

"name":"products",

"type":2,

"isSystem":false,

"id":"10462"

ReturnCodes

Examples

shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/truncate

HTTP/1.1200OK

location:/_api/collection/products/truncate

showresponsebody

Creating

GettingInformationaboutaCollection

Returninformationaboutacollection

returnsacollection

GET/_api/collection/{collection-name}

PathParameters

Theresultisanobjectdescribingthecollectionwiththefollowingattributes:

id:Theidentifierofthecollection.

name:Thenameofthecollection.

status:Thestatusofthecollectionasnumber.

1:newborncollection2:unloaded3:loaded4:intheprocessofbeingunloaded5:deleted6:loading

Everyotherstatusindicatesacorruptedcollection.

type:Thetypeofthecollectionasnumber.

2:documentcollection(normalcase)3:edgescollection

isSystem:Iftruethenthecollectionisasystemcollection.

ReturnCodes

404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Readpropertiesofacollection

readsthepropertiesofthespecifiedcollection

GET/_api/collection/{collection-name}/properties

PathParameters

Inadditiontotheabove,theresultwillalwayscontainthewaitForSyncattribute,andthedoCompact,journalSize,andisVolatileattributesfortheMMFilesstorageengine.Thisisachievedbyforcingaloadoftheunderlyingcollection.

waitForSync:Iftruethencreating,changingorremovingdocumentswillwaituntilthedatahasbeensynchronizedtodisk.

doCompact:Whetherornotthecollectionwillbecompacted.ThisoptionisonlypresentfortheMMFilesstorageengine.

journalSize:Themaximalsizesettingforjournals/datafilesinbytes.ThisoptionisonlypresentfortheMMFilesstorageengine.

keyOptions:JSONobjectwhichcontainskeygenerationoptions:

type:specifiesthetypeofthekeygenerator.Thecurrentlyavailablegeneratorsaretraditionalandautoincrement.allowUserKeys:ifsettotrue,thenitisallowedtosupplyownkeyvaluesinthe_keyattributeofadocument.Ifsettofalse,thenthekeygeneratorissolelyresponsibleforgeneratingkeysandsupplyingownkeyvaluesinthe_keyattributeofdocumentsisconsideredanerror.

isVolatile:IftruethenthecollectiondatawillbekeptinmemoryonlyandArangoDBwillnotwriteorsyncthedatatodisk.ThisoptionisonlypresentfortheMMFilesstorageengine.

GettingInformation

Inaclustersetup,theresultwillalsocontainthefollowingattributes:

numberOfShards:thenumberofshardsofthecollection.

shardKeys:containsthenamesofdocumentattributesthatareusedtodeterminethetargetshardfordocuments.

replicationFactor:containshowmanycopiesofeachshardarekeptondifferentDBServers.

Example:Usinganidentifier:

shell>curl--dump-http://localhost:8529/_api/collection/10401/properties

HTTP/1.1200OK

location:/_api/collection/10401/properties

"code":200,

"error":false,

"status":3,

"name":"products",

"keyOptions":{

"lastValue":0

"type":2,

"indexBuckets":8,

"doCompact":true,

"waitForSync":true,

"id":"10401",

"isSystem":false,

"isVolatile":false

Example:Usinganame:

shell>curl--dump-http://localhost:8529/_api/collection/products/properties

HTTP/1.1200OK

location:/_api/collection/products/properties

"code":200,

"error":false,

"status":3,

"name":"products",

"keyOptions":{

"lastValue":0

"type":2,

"indexBuckets":8,

"doCompact":true,

"waitForSync":true,

"id":"10409",

GettingInformation

"isSystem":false,

"isVolatile":false

ReturnCodes

Examples

Usinganidentifier:

shell>curl--dump-http://localhost:8529/_api/collection/10401/properties

HTTP/1.1200OK

location:/_api/collection/10401/properties

showresponsebodyUsinganame:

shell>curl--dump-http://localhost:8529/_api/collection/products/properties

HTTP/1.1200OK

showresponsebody

Returnnumberofdocumentsinacollection

Countsthedocumentsinacollection

GET/_api/collection/{collection-name}/count

PathParameters

Inadditiontotheabove,theresultalsocontainsthenumberofdocuments.Notethatthiswillalwaysloadthecollectionintomemory.

count:Thenumberofdocumentsinsidethecollection.

Example:Requestingthenumberofdocuments:

shell>curl--dump-http://localhost:8529/_api/collection/products/count

HTTP/1.1200OK

location:/_api/collection/products/count

"code":200,

GettingInformation

"error":false,

"name":"products",

"keyOptions":{

"lastValue":10367

"isVolatile":false,

"status":3,

"count":100,

"doCompact":true,

"type":2,

"indexBuckets":8,

"waitForSync":true,

"id":"10065",

"isSystem":false

ReturnCodes

Examples

Requestingthenumberofdocuments:

shell>curl--dump-http://localhost:8529/_api/collection/products/count

HTTP/1.1200OK

location:/_api/collection/products/count

showresponsebody

Returnstatisticsforacollection

Fetchthestatisticsofacollection

GET/_api/collection/{collection-name}/figures

PathParameters

Inadditiontotheabove,theresultalsocontainsthenumberofdocumentsandadditionalstatisticalinformationaboutthecollection.Note:Thiswillalwaysloadthecollectionintomemory.

Note:collectiondatathatarestoredinthewrite-aheadlogonlyarenotreportedintheresults.Whenthewrite-aheadlogiscollected,documentsmightbeaddedtojournalsanddatafilesofthecollection,whichmaymodifythefiguresofthecollection.

Additionally,thefilesizesofcollectionandindexparameterJSONfilesarenotreported.Thesefilesshouldnormallyhaveasizeofafewbyteseach.PleasealsonotethatthefileSizevaluesarereportedinbytesandreflectthelogicalfilesizes.Somefilesystemsmayuseoptimisations(e.g.sparsefiles)sothattheactualphysicalfilesizeissomewhatdifferent.Directoriesandsub-directoriesmayalsorequirespaceinthefilesystem,butthisspaceisnotreportedinthefileSizeresults.

Thatmeansthatthefiguresreporteddonotreflecttheactualdiskusageofthecollectionwith100%accuracy.TheactualdiskusageofacollectionisnormallyslightlyhigherthanthesumofthereportedfileSizevalues.StillthesumofthefileSizevaluescanstillbeusedasalowerboundapproximationofthediskusage.

AjsondocumentwiththesePropertiesisreturned:

GettingInformation

HTTP200

Returnsinformationaboutthecollection:

count:Thenumberofdocumentscurrentlypresentinthecollection.journalSize:Themaximalsizeofajournalordatafileinbytes.figures:

datafiles:count:Thenumberofdatafiles.fileSize:Thetotalfilesizeofdatafiles(inbytes).

uncollectedLogfileEntries:Thenumberofmarkersinthewrite-aheadlogforthiscollectionthathavenotbeentransferredtojournalsordatafiles.documentReferences:ThenumberofreferencestodocumentsindatafilesthatJavaScriptcodecurrentlyholds.Thisinformationcanbeusedfordebuggingcompactionandunloadissues.compactionStatus:

message:Theactionthatwasperformedwhenthecompactionwaslastrunforthecollection.Thisinformationcanbeusedfordebuggingcompactionissues.time:Thepointintimethecompactionforthecollectionwaslastexecuted.Thisinformationcanbeusedfordebuggingcompactionissues.

compactors:count:Thenumberofcompactorfiles.fileSize:Thetotalfilesizeofallcompactorfiles(inbytes).

dead:count:Thenumberofdeaddocuments.Thisincludesdocumentversionsthathavebeendeletedorreplacedbyanewerversion.Documentsdeletedorreplacedthatarecontainedthewrite-aheadlogonlyarenotreportedinthisfigure.deletion:Thetotalnumberofdeletionmarkers.Deletionmarkersonlycontainedinthewrite-aheadlogarenotreportinginthisfigure.size:Thetotalsizeinbytesusedbyalldeaddocuments.

indexes:count:Thetotalnumberofindexesdefinedforthecollection,includingthepre-definedindexes(e.g.primaryindex).size:Thetotalmemoryallocatedforindexesinbytes.

readcache:count:Thenumberofrevisionsofthiscollectionstoredinthedocumentrevisionscache.size:Thememoryusedforstoringtherevisionsofthiscollectioninthedocumentrevisionscache(inbytes).Thisfiguredoesnotincludethedocumentdatabutonlymappingsfromdocumentrevisionidstocacheentrylocations.

waitingFor:Anoptionalstringvaluethatcontainsinformationaboutwhichobjecttypeisattheheadofthecollection'scleanupqueue.Thisinformationcanbeusedfordebuggingcompactionandunloadissues.alive:

count:Thenumberofcurrentlyactivedocumentsinalldatafilesandjournalsofthecollection.Documentsthatarecontainedinthewrite-aheadlogonlyarenotreportedinthisfigure.size:Thetotalsizeinbytesusedbyallactivedocumentsofthecollection.Documentsthatarecontainedinthewrite-aheadlogonlyarenotreportedinthisfigure.

lastTick:Thetickofthelastmarkerthatwasstoredinajournalofthecollection.Thismightbe0ifthecollectiondoesnotyethaveajournal.journals:

count:Thenumberofjournalfiles.fileSize:Thetotalfilesizeofalljournalfiles(inbytes).

revisions:count:Thenumberofrevisionsofthiscollectionmanagedbythestorageengine.size:Thememoryusedforstoringtherevisionsofthiscollectioninthestorageengine(inbytes).Thisfiguredoesnotincludethedocumentdatabutonlymappingsfromdocumentrevisionidstostorageenginedatafilepositions.

Example:Usinganidentifierandrequestingthefiguresofthecollection:

GettingInformation

shell>curl--dump-http://localhost:8529/_api/collection/products/figures

HTTP/1.1200OK

location:/_api/collection/products/figures

"code":200,

"error":false,

"name":"products",

"keyOptions":{

"lastValue":10379

"isVolatile":false,

"isSystem":false,

"status":3,

"count":1,

"figures":{

"indexes":{

"count":1,

"size":32128

"documentReferences":0,

"waitingFor":"-",

"alive":{

"count":1,

"size":72

"dead":{

"count":0,

"size":0,

"deletion":0

"compactionStatus":{

"message":"skippedcompactionbecausecollectionhasnodatafiles",

"time":"2018-01-25T19:13:38Z",

"count":0,

"filesCombined":0,

"bytesRead":0,

"bytesWritten":0

"datafiles":{

"count":0,

"fileSize":0

"journals":{

"count":1,

"fileSize":33554432

"compactors":{

"count":0,

"fileSize":0

"revisions":{

"count":1,

"size":48192

"lastTick":10381,

"uncollectedLogfileEntries":0

"doCompact":true,

"type":2,

"indexBuckets":8,

"id":"10375"

ReturnCodes

GettingInformation

200:Returnsinformationaboutthecollection:

ResponseBody

count:Thenumberofdocumentscurrentlypresentinthecollection.journalSize:Themaximalsizeofajournalordatafileinbytes.figures:

datafiles:count:Thenumberofdatafiles.fileSize:Thetotalfilesizeofdatafiles(inbytes).uncollectedLogfileEntries:Thenumberofmarkersinthewrite-aheadlogforthiscollectionthathavenotbeentransferredtojournalsordatafiles.lastTick:Thetickofthelastmarkerthatwasstoredinajournalofthecollection.Thismightbe0ifthecollectiondoesnotyethaveajournal.compactionStatus:message:Theactionthatwasperformedwhenthecompactionwaslastrunforthecollection.Thisinformationcanbeusedfordebuggingcompactionissues.time:Thepointintimethecompactionforthecollectionwaslastexecuted.Thisinformationcanbeusedfordebuggingcompactionissues.dead:count:Thenumberofdeaddocuments.Thisincludesdocumentversionsthathavebeendeletedorreplacedbyanewerversion.Documentsdeletedorreplacedthatarecontainedthewrite-aheadlogonlyarenotreportedinthisfigure.deletion:Thetotalnumberofdeletionmarkers.Deletionmarkersonlycontainedinthewrite-aheadlogarenotreportinginthisfigure.size:Thetotalsizeinbytesusedbyalldeaddocuments.compactors:count:Thenumberofcompactorfiles.fileSize:Thetotalfilesizeofallcompactorfiles(inbytes).readcache:count:Thenumberofrevisionsofthiscollectionstoredinthedocumentrevisionscache.size:Thememoryusedforstoringtherevisionsofthiscollectioninthedocumentrevisionscache(inbytes).Thisfiguredoesnotincludethedocumentdatabutonlymappingsfromdocumentrevisionidstocacheentrylocations.waitingFor:Anoptionalstringvaluethatcontainsinformationaboutwhichobjecttypeisattheheadofthecollection'scleanupqueue.Thisinformationcanbeusedfordebuggingcompactionandunloadissues.alive:count:Thenumberofcurrentlyactivedocumentsinalldatafilesandjournalsofthecollection.Documentsthatarecontainedinthewrite-aheadlogonlyarenotreportedinthisfigure.size:Thetotalsizeinbytesusedbyallactivedocumentsofthecollection.Documentsthatarecontainedinthewrite-aheadlogonlyarenotreportedinthisfigure.documentReferences:ThenumberofreferencestodocumentsindatafilesthatJavaScriptcodecurrentlyholds.Thisinformationcanbeusedfordebuggingcompactionandunloadissues.indexes:count:Thetotalnumberofindexesdefinedforthecollection,includingthepre-definedindexes(e.g.primaryindex).size:Thetotalmemoryallocatedforindexesinbytes.journals:count:Thenumberofjournalfiles.fileSize:Thetotalfilesizeofalljournalfiles(inbytes).revisions:count:Thenumberofrevisionsofthiscollectionmanagedbythestorageengine.size:Thememoryusedforstoringtherevisionsofthiscollectioninthestorageengine(inbytes).Thisfiguredoesnotincludethedocumentdatabutonlymappingsfromdocumentrevisionidstostorageenginedatafilepositions.

shell>curl--dump-http://localhost:8529/_api/collection/products/figures

HTTP/1.1200OK

GettingInformation

location:/_api/collection/products/figures

showresponsebody

Returncollectionrevisionid

Retrievethecollectionsrevisionid

GET/_api/collection/{collection-name}/revision

PathParameters

Inadditiontotheabove,theresultwillalsocontainthecollection'srevisionid.Therevisionidisaserver-generatedstringthatclientscanusetocheckwhetherdatainacollectionhaschangedsincethelastrevisioncheck.

revision:Thecollectionrevisionidasastring.

Example:Retrievingtherevisionofacollection

shell>curl--dump-http://localhost:8529/_api/collection/products/revision

HTTP/1.1200OK

location:/_api/collection/products/revision

"code":200,

"error":false,

"isVolatile":false,

"isSystem":false,

"id":"10417",

"keyOptions":{

"lastValue":0

"revision":"0",

"indexBuckets":8,

"type":2,

"name":"products",

"doCompact":true,

"status":3

ReturnCodes

Examples

Retrievingtherevisionofacollection

shell>curl--dump-http://localhost:8529/_api/collection/products/revision

HTTP/1.1200OK

GettingInformation

location:/_api/collection/products/revision

showresponsebody

Returnchecksumforthecollection

returnsachecksumforthespecifiedcollection

GET/_api/collection/{collection-name}/checksum

PathParameters

QueryParameters

withRevisions(optional):Whetherornottoincludedocumentrevisionidsinthechecksumcalculation.withData(optional):Whetherornottoincludedocumentbodydatainthechecksumcalculation.

Willcalculateachecksumofthemeta-data(keysandoptionallyrevisionids)andoptionallythedocumentdatainthecollection.

ThechecksumcanbeusedtocompareiftwocollectionsondifferentArangoDBinstancescontainthesamecontents.Thecurrentrevisionofthecollectionisreturnedtoosoonecanmakesurethechecksumsarecalculatedforthesamestateofdata.

Bydefault,thechecksumwillonlybecalculatedonthe_keysystemattributeofthedocumentscontainedinthecollection.Foredgecollections,thesystemattributes_fromand_towillalsobeincludedinthecalculation.

BysettingtheoptionalqueryparameterwithRevisionstotrue,thenrevisionids(_revsystemattributes)areincludedinthechecksumming.

ByprovidingtheoptionalqueryparameterwithDatawithavalueoftrue,theuser-defineddocumentattributeswillbeincludedinthecalculationtoo.Note:Includinguser-definedattributeswillmakethechecksummingslower.

checksum:Thecalculatedchecksumasanumber.

revision:Thecollectionrevisionidasastring.

Note:thismethodisnotavailableinacluster.

Example:Retrievingthechecksumofacollection:

shell>curl--dump-http://localhost:8529/_api/collection/products/checksum

HTTP/1.1200OK

location:/_api/collection/products/checksum

"code":200,

"error":false,

"isSystem":false,

"revision":"_WQ47VrK--_",

"type":2,

"checksum":"10263933996432733528",

"id":"10041",

"name":"products",

"status":3

GettingInformation

Example:Retrievingthechecksumofacollectionincludingthecollectiondata,butnottherevisions:

shell>curl--dump-http://localhost:8529/_api/collection/products/checksum?withRevisions=false&withData=true

HTTP/1.1200OK

"code":200,

"error":false,

"isSystem":false,

"revision":"_WQ47VsK--_",

"type":2,

"checksum":"9794134053781729250",

"id":"10053",

"name":"products",

"status":3

ReturnCodes

Examples

Retrievingthechecksumofacollection:

shell>curl--dump-http://localhost:8529/_api/collection/products/checksum

HTTP/1.1200OK

showresponsebodyRetrievingthechecksumofacollectionincludingthecollectiondata,butnottherevisions:

shell>curl--dump-http://localhost:8529/_api/collection/products/checksum?

withRevisions=false&withData=true

HTTP/1.1200OK

showresponsebody

readsallcollections

returnsallcollections

GET/_api/collection

GettingInformation

QueryParameters

excludeSystem(optional):Whetherornotsystemcollectionsshouldbeexcludedfromtheresult.

Returnsanobjectwithanattributecollectionscontaininganarrayofallcollectiondescriptions.Thesameinformationisalsoavailableinthenamesasanobjectwiththecollectionnamesaskeys.

ByprovidingtheoptionalqueryparameterexcludeSystemwithavalueoftrue,allsystemcollectionswillbeexcludedfromtheresponse.

Example:Returninformationaboutallcollections:

shell>curl--dump-http://localhost:8529/_api/collection

HTTP/1.1200OK

"error":false,

"code":200,

"result":[

"id":"28",

"name":"_statisticsRaw",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_statisticsRaw"

"id":"11",

"name":"_modules",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_modules"

"id":"45",

"name":"_queues",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_queues"

"id":"26",

"name":"_aqlfunctions",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_aqlfunctions"

"id":"60",

"name":"_appbundles",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_appbundles"

"id":"2",

"name":"_graphs",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_graphs"

GettingInformation

"id":"13",

"name":"_routing",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_routing"

"id":"47",

"name":"_jobs",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_jobs"

"id":"98",

"name":"animals",

"status":3,

"type":2,

"isSystem":false,

"globallyUniqueId":"h68719E5AC6E7/98"

"id":"43",

"name":"_frontend",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_frontend"

"id":"6",

"name":"_users",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_users"

"id":"33",

"name":"_statistics",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_statistics"

"id":"38",

"name":"_statistics15",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_statistics15"

"id":"55",

"name":"_apps",

"status":3,

"type":2,

"isSystem":true,

"globallyUniqueId":"_apps"

"id":"92",

"name":"demo",

"status":3,

"type":2,

"isSystem":false,

"globallyUniqueId":"h68719E5AC6E7/92"

ReturnCodes

GettingInformation

200:Thelistofcollections

Examples

Returninformationaboutallcollections:

shell>curl--dump-http://localhost:8529/_api/collection

HTTP/1.1200OK

showresponsebody

GettingInformation

ModifyingaCollection

Loadcollection

loadsacollection

PUT/_api/collection/{collection-name}/load

PathParameters

Loadsacollectionintomemory.Returnsthecollectiononsuccess.

Therequestbodyobjectmightoptionallycontainthefollowingattribute:

count:Ifset,thiscontrolswhetherthereturnvalueshouldincludethenumberofdocumentsinthecollection.Settingcounttofalsemayspeeduploadingacollection.Thedefaultvalueforcountistrue.

Onsuccessanobjectwiththefollowingattributesisreturned:

count:Thenumberofdocumentsinsidethecollection.Thisisonlyreturnedifthecountinputparametersissettotrueorhasnotbeenspecified.

type:Thecollectiontype.Validtypesare:

Example:

shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/load

HTTP/1.1200OK

location:/_api/collection/products/load

"code":200,

"error":false,

"type":2,

"count":0,

"status":3,

"id":"10426",

"isSystem":false,

"name":"products"

ReturnCodes

Examples

shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/load

Modifying

HTTP/1.1200OK

location:/_api/collection/products/load

showresponsebody

Unloadcollection

unloadsacollection

PUT/_api/collection/{collection-name}/unload

PathParameters

collection-name(required):

Removesacollectionfrommemory.Thiscalldoesnotdeleteanydocuments.Youcanusethecollectionafterwards;inwhichcaseitwillbeloadedintomemory,again.Onsuccessanobjectwiththefollowingattributesisreturned:

Example:

shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/unload

HTTP/1.1200OK

location:/_api/collection/products/unload

"code":200,

"error":false,

"status":4,

"name":"products",

"type":2,

"isSystem":false,

"id":"10470"

ReturnCodes

Examples

shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/unload

HTTP/1.1200OK

Modifying

location:/_api/collection/products/unload

showresponsebody

LoadIndexesintoMemory

PUT/_api/collection/{collection-name}/loadIndexesIntoMemory

PathParameters

collection-name(required):

Thisroutetriestocacheallindexentriesofthiscollectionintothemainmemory.Thereforeititeratesoverallindexesofthecollectionandstorestheindexedvalues,nottheentiredocumentdata,inmemory.Alllookupsthatcouldbefoundinthecachearemuchfasterthanlookupsnotstoredinthecachesoyougetaniceperformanceboost.Itisalsoguaranteedthatthecacheisconsistentwiththestoreddata.

ForthetimebeingthisfunctionisonlyusefulonRocksDBstorageengine,asinMMFilesengineallindexesareinmemoryanyways.

OnRocksDBthisfunctionhonorsallmemorylimits,iftheindexesyouwanttoloadaresmallerthanyourmemorylimitthisfunctionguaranteesthatmostindexvaluesarecached.Iftheindexislargerthanyourmemorylimitthisfunctionwillfillupvaluesuptothislimitandforthetimebeingthereisnowaytocontrolwhichindexesofthecollectionshouldhavepriorityoverothers.

Onsucessthisfunctionreturnsanobjectwithattributeresultsettotrue

Example:

shell>curl-XPUT--dump-http://localhost:8529/_api/collection/products/loadIndexesIntoMemory

HTTP/1.1200OK

location:/_api/collection/products/loadIndexesIntoMemory

"code":200,

"error":false,

"result":true

ReturnCodes

200:Iftheindexeshaveallbeenloaded400:Ifthecollection-nameismissing,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Examples

shell>curl-XPUT--dump-

http://localhost:8529/_api/collection/products/loadIndexesIntoMemory

HTTP/1.1200OK

location:/_api/collection/products/loadIndexesIntoMemory

Modifying

showresponsebody

Changepropertiesofacollection

changesacollection

PUT/_api/collection/{collection-name}/properties

PathParameters

Changesthepropertiesofacollection.Expectsanobjectwiththeattribute(s)

waitForSync:Iftruethencreatingorchangingadocumentwillwaituntilthedatahasbeensynchronizedtodisk.

journalSize:Themaximalsizeofajournalordatafileinbytes.Thevaluemustbeatleast1048576(1MB).NotethatwhenchangingthejournalSizevalue,itwillonlyhaveaneffectforadditionaljournalsordatafilesthatarecreated.Alreadyexistingjournalsordatafileswillnotbeaffected.

Onsuccessanobjectwiththefollowingattributesisreturned:

waitForSync:Thenewvalue.

journalSize:Thenewvalue.

isVolatile:IftruethenthecollectiondatawillbekeptinmemoryonlyandArangoDBwillnotwriteorsyncthedatatodisk.

doCompact:Whetherornotthecollectionwillbecompacted.

keyOptions:JSONobjectwhichcontainskeygenerationoptions:

type:specifiesthetypeofthekeygenerator.Thecurrentlyavailablegeneratorsaretraditionalandautoincrement.allowUserKeys:ifsettotrue,thenitisallowedtosupplyownkeyvaluesinthe_keyattributeofadocument.Ifsettofalse,thenthekeygeneratorissolelyresponsibleforgeneratingkeysandsupplyingownkeyvaluesinthe_keyattributeofdocumentsisconsideredanerror.

Note:exceptforwaitForSync,journalSizeandname,collectionpropertiescannotbechangedonceacollectioniscreated.Torenameacollection,therenameendpointmustbeused.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/collection/products/properties<<EOF

"waitForSync":true

HTTP/1.1200OK

"code":200,

"error":false,

Modifying

"status":3,

"name":"products",

"keyOptions":{

"lastValue":0

"type":2,

"indexBuckets":8,

"doCompact":true,

"waitForSync":true,

"id":"10443",

"isSystem":false,

"isVolatile":false

ReturnCodes

Examples

shell>curl-XPUT--data-binary@---dump-

http://localhost:8529/_api/collection/products/properties<<EOF

"waitForSync":true

HTTP/1.1200OK

showresponsebody

Renamecollection

renamesacollection

PUT/_api/collection/{collection-name}/rename

PathParameters

collection-name(required):Thenameofthecollectiontorename.

Renamesacollection.Expectsanobjectwiththeattribute(s)

name:Thenewname.

Itreturnsanobjectwiththeattributes

name:Thenewnameofthecollection.

Modifying

Ifrenamingthecollectionsucceeds,thenthecollectionisalsorenamedinallgraphdefinitionsinsidethe_graphscollectioninthecurrentdatabase.

Note:thismethodisnotavailableinacluster.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/collection/products1/rename<<EOF

"name":"newname"

HTTP/1.1200OK

location:/_api/collection/products1/rename

"code":200,

"error":false,

"status":3,

"name":"newname",

"type":2,

"isSystem":false,

"id":"10453"

ReturnCodes

Examples

http://localhost:8529/_api/collection/products1/rename<<EOF

"name":"newname"

HTTP/1.1200OK

location:/_api/collection/products1/rename

showresponsebody

Rotatejournalofacollection

rotatesthejournalofacollection

PUT/_api/collection/{collection-name}/rotate

PathParameters

Modifying

Rotatesthejournalofacollection.Thecurrentjournalofthecollectionwillbeclosedandmadearead-onlydatafile.Thepurposeoftherotatemethodistomakethedatainthefileavailableforcompaction(compactionisonlyperformedforread-onlydatafiles,andnotforjournals).

Savingnewdatainthecollectionsubsequentlywillcreateanewjournalfileautomaticallyifthereisnocurrentjournal.

Itreturnsanobjectwiththeattributes

result:willbetrueifrotationsucceeded

Note:thismethodisspecificfortheMMFilesstorageengine,andthereitisnotavailableinacluster.

Example:Rotatingthejournal:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/collection/products/rotate<<EOF

HTTP/1.1200OK

location:/_api/collection/products/rotate

"code":200,

"error":false,

"result":true

Example:Rotatingifnojournalexists:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/collection/products/rotate<<EOF

HTTP/1.1400BadRequest

"error":true,

"errorMessage":"nojournal",

"code":400,

"errorNum":1105

ReturnCodes

400:Ifthecollectioncurrentlyhasnojournal,HTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Examples

Rotatingthejournal:

http://localhost:8529/_api/collection/products/rotate<<EOF

Modifying

HTTP/1.1200OK

location:/_api/collection/products/rotate

showresponsebodyRotatingifnojournalexists:

http://localhost:8529/_api/collection/products/rotate<<EOF

showresponsebody

Modifying

HTTPInterfaceforDocumentsInthischapterwedescribetheRESTAPIofArangoDBfordocuments.

BasicapproachDetailedAPIdescription

Documents

Documents,Keys,HandlesandRevisions

DocumentsinArangoDBareJSONobjects.Theseobjectscanbenested(toanydepth)andmaycontainlists.Eachdocumenthasauniqueprimarykeywhichidentifiesitwithinitscollection.Furthermore,eachdocumentisuniquelyidentifiedbyitsdocumenthandleacrossallcollectionsinthesamedatabase.Differentrevisionsofthesamedocument(identifiedbyitshandle)canbedistinguishedbytheirdocumentrevision.Anytransactiononlyeverseesasinglerevisionofadocument.

Hereisanexampledocument:

"_id":"myusers/3456789",

"_key":"3456789",

"_rev":"14253647",

"firstName":"John",

"lastName":"Doe",

"address":{

"street":"RoadToNowhere1",

"city":"Gotham"

"hobbies":[

{name:"swimming",howFavorite:10},

{name:"biking",howFavorite:6},

{name:"programming",howFavorite:4}

Alldocumentscontainspecialattributes:thedocumenthandleisstoredasastringin_id,thedocument'sprimarykeyin_keyandthedocumentrevisionin_rev.Thevalueofthe_keyattributecanbespecifiedbytheuserwhencreatingadocument._idand_keyvaluesareimmutableoncethedocumenthasbeencreated.The_revvalueismaintainedbyArangoDBautomatically.

DocumentHandle

Adocumenthandleuniquelyidentifiesadocumentinthedatabase.Itisastringandconsistsofthecollection'snameandthedocumentkey(_keyattribute)separatedby/.

DocumentKey

Adocumentkeyuniquelyidentifiesadocumentinthecollectionitisstoredin.Itcanandshouldbeusedbyclientswhenspecificdocumentsarequeried.Thedocumentkeyisstoredinthe_keyattributeofeachdocument.ThekeyvaluesareautomaticallyindexedbyArangoDBinacollection'sprimaryindex.Thuslookingupadocumentbyitskeyisafastoperation.The_keyvalueofadocumentisimmutableoncethedocumenthasbeencreated.Bydefault,ArangoDBwillauto-generateadocumentkeyifno_keyattributeisspecified,andusetheuser-specified_keyotherwise.

Thisbehaviorcanbechangedonaper-collectionlevelbycreatingcollectionswiththekeyOptionsattribute.

UsingkeyOptionsitispossibletodisallowuser-specifiedkeyscompletely,ortoforceaspecificregimeforauto-generatingthe_keyvalues.

DocumentRevision

AsArangoDBsupportsMVCC(MultipleVersionConcurrencyControl),documentscanexistinmorethanonerevision.ThedocumentrevisionistheMVCCtokenusedtospecifyaparticularrevisionofadocument(identifiedbyits_id).Itisastringvaluecurrentlycontaininganintegernumberandisuniquewithinthelistofdocumentrevisionsforasingledocument.Documentrevisionscanbeusedtoconditionallyquery,update,replaceordeletedocumentsinthedatabase.Inordertofindaparticularrevisionofadocument,youneedthedocumenthandleorkey,andthedocumentrevision.

ArangoDBuses64bitunsignedintegervaluestomaintaindocumentrevisionsinternally.Whenreturningdocumentrevisionstoclients,ArangoDBwillputthemintoastringtoensuretherevisionisnotclippedbyclientsthatdonotsupportbigintegers.ClientsshouldtreattherevisionreturnedbyArangoDBasanopaquestringwhentheystoreoruseitlocally.ThiswillallowArangoDBtochangetheformatofrevisionslaterifthisshouldberequired.Clientscanuserevisionstoperformsimpleequality/non-equalitycomparisons(e.g.tocheckwhetheradocumenthaschangedornot),buttheyshouldnotuserevisionidstoperformgreater/lessthancomparisonswiththemtocheckifadocumentrevisionisolderthanoneanother,evenifthismightworkforsomecases.

DocumentEtag

ArangoDBtriestoadheretotheexistingHTTPstandardasfaraspossible.Tothisend,resultsofsingledocumentquerieshavetheHTTPheaderEtagsettothedocumentrevisionenclosedindoublequotes.

Thebasicoperations(create,read,exists,replace,update,delete)fordocumentsaremappedtothestandardHTTPmethods(POST,GET,HEAD,PUT,PATCHandDELETE).

Ifyoumodifyadocument,youcanusetheIf-Matchfieldtodetectconflicts.TherevisionofadocumentcanbecheckingusingtheHTTPmethodHEAD.

MultipleDocumentsinasingleRequest

BeginningwithArangoDB3.0thebasicdocumentAPIhasbeenextendedtohandlenotonlysingledocumentsbutmultipledocumentsinasinglerequest.Thisiscrucialforperformance,inparticularintheclustersituation,inwhichasinglerequestcaninvolvemultiplenetworkhopswithinthecluster.AnotheradvantageisthatitreducestheoverheadoftheHTTPprotocolandindividualnetworkroundtripsbetweentheclientandtheserver.ThegeneralideatoperformmultipledocumentoperationsinasinglerequestistouseaJSONarrayofobjectsintheplaceofasingledocument.Asaconsequence,documentkeys,handlesandrevisionsforpreconditionshavetobesuppliedembeddedintheindividualdocumentsgiven.Multipledocumentoperationsarerestrictedtoasingledocumentoredgecollections.SeetheAPIdescriptionsfordetails.

NotethattheGET,HEADandDELETEHTTPoperationsgenerallydonotallowtopassamessagebody.Thus,theycannotbeusedtoperformmultipledocumentoperationsinonerequest.However,thereareotherendpointstorequestanddeletemultipledocumentsinonerequest.FIXME:ADDSENSIBLELINKSHERE.

URIofaDocument

AnydocumentcanberetrievedusingitsuniqueURI:

http://server:port/_api/document/<document-handle>

Forexample,assumingthatthedocumenthandleisdemo/362549736,thentheURLofthatdocumentis:

http://localhost:8529/_api/document/demo/362549736

TheaboveURLschemadoesnotspecifyadatabasenameexplicitly,sothedefaultdatabase_systemwillbeused.Toexplicitlyspecifythedatabasecontext,usethefollowingURLschema:

http://server:port/_db/<database-name>/_api/document/<document-handle>

Example:

http://localhost:8529/_db/mydb/_api/document/demo/362549736

Note:ThefollowingexamplesusetheshortURLformatforbrevity.

Thedocumentrevisionisreturnedinthe"Etag"HTTPheaderwhenrequestingadocument.

IfyouobtainadocumentusingGETandyouwanttocheckwhetheranewerrevisionisavailable,thenyoucanusetheIf-None-Matchheader.Ifthedocumentisunchanged,aHTTP412(preconditionfailed)errorisreturned.

Ifyouwanttoquery,replace,updateordeleteadocument,thenyoucanusetheIf-Matchheader.Ifthedocumenthaschanged,thentheoperationisabortedandanHTTP412errorisreturned.

WorkingwithDocumentsusingREST

Readdocument

readsasingledocument

GET/_api/document/{document-handle}

PathParameters

document-handle(required):Thehandleofthedocument.

HeaderParameters

If-None-Match(optional):Ifthe"If-None-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasadifferentrevisionthanthegivenEtag.OtherwiseanHTTP304isreturned.If-Match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.

Returnsthedocumentidentifiedbydocument-handle.Thereturneddocumentcontainsthreespecialattributes:_idcontainingthedocumenthandle,_keycontainingkeywhichuniquelyidentifiesadocumentinagivencollectionand_revcontainingtherevision.

Example:Useadocumenthandle:

shell>curl--dump-http://localhost:8529/_api/document/products/11042

HTTP/1.1200OK

etag:"_WQ47YXa--_"

"_key":"11042",

"_id":"products/11042",

"_rev":"_WQ47YXa--_",

"hello":"world"

Example:UseadocumenthandleandanEtag:

shell>curl--header'If-None-Match:"_WQ47Yc2--_"'--dump-http://localhost:8529/_api/document/products/11118

Example:Unknowndocumenthandle:

shell>curl--dump-http://localhost:8529/_api/document/products/unknownhandle

HTTP/1.1404NotFound

"error":true,

"errorMessage":"collectionnotfound:products",

"code":404,

"errorNum":1203

ReturnCodes

200:isreturnedifthedocumentwasfound304:isreturnedifthe"If-None-Match"headerisgivenandthedocumenthasthesameversion404:isreturnedifthedocumentorcollectionwasnotfound412:isreturnedifan"If-Match"headerisgivenandthefounddocumenthasadifferentversion.Theresponsewillalsocontainthefounddocument'scurrentrevisioninthe_revattribute.Additionally,theattributes_idand_keywillbereturned.

Examples

Useadocumenthandle:

HTTP/1.1200OK

etag:"_WQ47YXa--_"

showresponsebodyUseadocumenthandleandanEtag:

shell>curl--header'If-None-Match:"_WQ47Yc2--_"'--dump-

http://localhost:8529/_api/document/products/11118

Unknowndocumenthandle:

shell>curl--dump-http://localhost:8529/_api/document/products/unknownhandle

HTTP/1.1404NotFound

showresponsebody

Changesin3.0from2.8:

Therevqueryparameterhasbeenwithdrawn.ThesameeffectcanbeachievedwiththeIf-MatchHTTPheader.

Readdocumentheader

readsasingledocumenthead

HEAD/_api/document/{document-handle}

PathParameters

document-handle(required):Thehandleofthedocument.

HeaderParameters

If-None-Match(optional):Ifthe"If-None-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Ifthecurrentdocument

revisionisnotequaltothespecifiedEtag,anHTTP200responseisreturned.Ifthecurrentdocumentrevisionisidenticaltothe

specifiedEtag,thenanHTTP304isreturned.If-Match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.

LikeGET,butonlyreturnstheheaderfieldsandnotthebody.Youcanusethiscalltogetthecurrentrevisionofadocumentorcheckifthedocumentwasdeleted.

Example:

shell>curl-XHEAD--dump-http://localhost:8529/_api/document/products/11102

ReturnCodes

200:isreturnedifthedocumentwasfound304:isreturnedifthe"If-None-Match"headerisgivenandthedocumenthasthesameversion404:isreturnedifthedocumentorcollectionwasnotfound412:isreturnedifan"If-Match"headerisgivenandthefounddocumenthasadifferentversion.Theresponsewillalsocontainthefounddocument'scurrentrevisionintheEtagheader.

Examples

shell>curl-XHEAD--dump-http://localhost:8529/_api/document/products/11102

Therevqueryparameterhasbeenwithdrawn.ThesameeffectcanbeachievedwiththeIf-MatchHTTPheader.

Readalldocuments

readsalldocumentsfromcollection

PUT/_api/simple/all-keys

QueryParameters

type:Thetypeoftheresult.Thefollowingvaluesareallowed:id:returnsanarrayofdocumentids(_idattributes)key:returnsanarrayofdocumentkeys(_keyattributes)path:returnsanarrayofdocumentURIpaths.Thisisthedefault.

collection:Thenameofthecollection.Thisisonlyforbackwardcompatibility.InArangoDBversions<3.0,theURLpathwas/_api/documentandthiswaspassedinviathequeryparameter"collection".Thiscombinationwasremoved.

Returnsanarrayofallkeys,ids,orURIpathsforalldocumentsinthecollectionidentifiedbycollection.Thetypeoftheresultarrayisdeterminedbythetypeattribute.

Notethattheresultshavenodefinedorderandthustheordershouldnotbereliedon.

Example:Returnalldocumentpaths

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all-keys<<EOF

"collection":"products"

HTTP/1.1201Created

"result":[

"/_db/_system/_api/document/products/11084",

"/_db/_system/_api/document/products/11087",

"/_db/_system/_api/document/products/11080"

"hasMore":false,

"cached":false,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":3,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.000125885009765625

"warnings":[]

"error":false,

"code":201

Example:Returnalldocumentkeys

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all-keys<<EOF

"collection":"products",

"type":"id"

HTTP/1.1201Created

"result":[

"products/11062",

"products/11065",

"products/11058"

"hasMore":false,

"cached":false,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":3,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.00013065338134765625

"warnings":[]

"error":false,

"code":201

Example:Collectiondoesnotexist

shell>curl--dump-http://localhost:8529/_api/document/doesnotexist

HTTP/1.1404NotFound

"error":true,

"errorMessage":"expectingGET/_api/document/<document-handle>",

"code":404,

"errorNum":1203

ReturnCodes

201:Allwentwell.404:Thecollectiondoesnotexist.

Examples

Returnalldocumentpaths

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all-keys

HTTP/1.1201Created

showresponsebodyReturnalldocumentkeys

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all-keys

"type":"id"

HTTP/1.1201Created

showresponsebodyCollectiondoesnotexist

shell>curl--dump-http://localhost:8529/_api/document/doesnotexist

HTTP/1.1404NotFound

showresponsebody

ThecollectionnameshouldnowbespecifiedintheURLpath.TheoldwaywiththeURLpath/_api/documentandtherequiredqueryparametercollectionstillworks.

Createdocument

createsdocuments

POST/_api/document/{collection}

PathParameters

collection(required):Thecollectioninwhichthecollectionistobecreated.

RequestBody(required)

AJSONrepresentationofasingledocumentorofanarrayofdocuments.

QueryParameters

collection(optional):Thenameofthecollection.Thisisonlyforbackwardcompatibility.InArangoDBversions<3.0,theURLpathwas/_api/documentandthisqueryparameterwasrequired.Thiscombinationstillworks,buttherecommendedwayistospecifythecollectionintheURLpath.waitForSync(optional):Waituntildocumenthasbeensyncedtodisk.returnNew(optional):Additionallyreturnthecompletenewdocumentundertheattributenewintheresult.silent(optional):Ifsettotrue,anemptyobjectwillbereturnedasresponse.Nometa-datawillbereturnedforthecreateddocument.Thisoptioncanbeusedtosavesomenetworktraffic.

Createsanewdocumentfromthedocumentgiveninthebody,unlessthereisalreadyadocumentwiththe_keygiven.Ifno_keyisgiven,anewunique_keyisgeneratedautomatically.

Thebodycanbeanarrayofdocuments,inwhichcasealldocumentsinthearrayareinsertedwiththesamesemanticsasforasingledocument.TheresultbodywillcontainaJSONarrayofthesamelengthastheinputarray,andeachentrycontainstheresultoftheoperationforthecorrespondinginput.IncaseofanerrortheentryisadocumentwithattributeserrorsettotrueanderrorCodesettotheerrorcodethathashappened.

Possiblygiven_idand_revattributesinthebodyarealwaysignored,theURLpartorthequeryparametercollectionrespectivelycounts.

Ifthedocumentwascreatedsuccessfully,thentheLocationheadercontainsthepathtothenewlycreateddocument.TheEtagheaderfieldcontainstherevisionofthedocument.Bothareonlysetinthesingledocumentcase.

Ifsilentisnotsettotrue,thebodyoftheresponsecontainsaJSONobject(singledocumentcase)withthefollowingattributes:

_idcontainsthedocumenthandleofthenewlycreateddocument_keycontainsthedocumentkey_revcontainsthedocumentrevision

Inthemulticasethebodyisanarrayofsuchobjects.

IfthecollectionparameterwaitForSyncisfalse,thenthecallreturnsassoonasthedocumenthasbeenaccepted.Itwillnotwaituntilthedocumentshavebeensyncedtodisk.

Optionally,thequeryparameterwaitForSynccanbeusedtoforcesynchronizationofthedocumentcreationoperationtodiskevenincasethatthewaitForSyncflaghadbeendisabledfortheentirecollection.Thus,thewaitForSyncqueryparametercanbeusedtoforcesynchronizationofjustthisspecificoperations.Tousethis,setthewaitForSyncparametertotrue.IfthewaitForSyncparameterisnot

specifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.

IfthequeryparameterreturnNewistrue,then,foreachgenerateddocument,thecompletenewdocumentisreturnedunderthenewattributeintheresult.

Example:Createadocumentinacollectionnamedproducts.Notethattherevisionidentifiermightormightnotbyequaltotheauto-generatedkey.

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products<<EOF

{"Hello":"World"}

HTTP/1.1201Created

etag:"_WQ47YT6--_"

location:/_db/_system/_api/document/products/10976

"_key":"10976",

"_rev":"_WQ47YT6--_"

Example:Createadocumentinacollectionnamedproductswithacollection-levelwaitForSyncvalueoffalse.

{"Hello":"World"}

HTTP/1.1202Accepted

etag:"_WQ47YRm--_"

"_key":"10950",

"_rev":"_WQ47YRm--_"

Example:Createadocumentinacollectionwithacollection-levelwaitForSyncvalueoffalse,butusingthewaitForSyncqueryparameter.

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products?waitForSync=true<<EOF

{"Hello":"World"}

HTTP/1.1201Created

etag:"_WQ47YW6--_"

"_key":"11027",

"_rev":"_WQ47YW6--_"

Example:Unknowncollectionname

{"Hello":"World"}

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":1203

Example:Illegaldocument

{1:"World"}

"error":true,

"errorMessage":"VPackErrorerror:Expecting'\"'or'}'",

"code":400,

"errorNum":600

Example:Insertmultipledocuments:

[{"Hello":"Earth"},{"Hello":"Venus"},{"Hello":"Mars"}]

HTTP/1.1202Accepted

"_key":"10991",

"_rev":"_WQ47YUa--_"

"_key":"10995",

"_rev":"_WQ47YUa--B"

"_key":"10997",

"_rev":"_WQ47YUa--D"

Example:UseofreturnNew:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products?returnNew=true<<EOF

{"Hello":"World"}

HTTP/1.1202Accepted

etag:"_WQ47YU2--_"

"_key":"11012",

"_rev":"_WQ47YU2--_",

"new":{

"_key":"11012",

"_rev":"_WQ47YU2--_",

"Hello":"World"

ReturnCodes

201:isreturnedifthedocumentswerecreatedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentswerecreatedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofonedocumentoranarrayofdocuments.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.409:isreturnedinthesingledocumentcaseifadocumentwiththesamequalifiersinanindexedattributeconflictswithanalreadyexistingdocumentandthusviolatesthatuniqueconstraint.Theresponsebodycontainsanerrordocumentinthiscase.Inthearraycaseonly201or202isreturned,butifanerroroccurred,theadditionalHTTPheaderX-Arango-Error-Codesisset,whichcontainsamapoftheerrorcodesthatoccurredtogetherwiththeirmultiplicities,asin:1205:10,1210:17whichmeansthatin10casestheerror1205"illegaldocumenthandle"andin17casestheerror1210"uniqueconstraintviolated"hashappened.

Examples

Createadocumentinacollectionnamedproducts.Notethattherevisionidentifiermightormightnotbyequaltotheauto-generatedkey.

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/document/products

{"Hello":"World"}

HTTP/1.1201Created

etag:"_WQ47YT6--_"

showresponsebody

Createadocumentinacollectionnamedproductswithacollection-levelwaitForSyncvalueoffalse.

{"Hello":"World"}

HTTP/1.1202Accepted

etag:"_WQ47YRm--_"

showresponsebodyCreateadocumentinacollectionwithacollection-levelwaitForSyncvalueoffalse,butusingthewaitForSyncqueryparameter.

shell>curl-XPOST--data-binary@---dump-

http://localhost:8529/_api/document/products?waitForSync=true<<EOF

{"Hello":"World"}

HTTP/1.1201Created

etag:"_WQ47YW6--_"

showresponsebodyUnknowncollectionname

{"Hello":"World"}

HTTP/1.1404NotFound

showresponsebodyIllegaldocument

{1:"World"}

showresponsebodyInsertmultipledocuments:

[{"Hello":"Earth"},{"Hello":"Venus"},{"Hello":"Mars"}]

HTTP/1.1202Accepted

"_key":"10991",

"_rev":"_WQ47YUa--_"

"_key":"10995",

"_rev":"_WQ47YUa--B"

"_key":"10997",

"_rev":"_WQ47YUa--D"

UseofreturnNew:

http://localhost:8529/_api/document/products?returnNew=true<<EOF

{"Hello":"World"}

HTTP/1.1202Accepted

etag:"_WQ47YU2--_"

showresponsebody

ThecollectionnameshouldnowbespecifiedintheURLpath.TheoldwaywiththeURLpath/_api/documentandtherequiredqueryparametercollectionstillworks.ThepossibilitytoinsertmultipledocumentswithoneoperationisnewandthequeryparameterreturnNewhasbeenadded.

Replacedocument

replacesadocument

PUT/_api/document/{document-handle}

AJSONrepresentationofasingledocument.

PathParameters

document-handle(required):ThisURLparametermustbeadocumenthandle.

QueryParameters

waitForSync(optional):Waituntildocumenthasbeensyncedtodisk.ignoreRevs(optional):Bydefault,orifthisissettotrue,the_revattributesinthegivendocumentisignored.Ifthisissettofalse,thenthe_revattributegiveninthebodydocumentistakenasaprecondition.Thedocumentisonlyreplacedifthecurrentrevisionistheonespecified.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentundertheattributeoldintheresult.returnNew(optional):Returnadditionallythecompletenewdocumentundertheattributenewintheresult.silent(optional):Ifsettotrue,anemptyobjectwillbereturnedasresponse.Nometa-datawillbereturnedforthereplaceddocument.Thisoptioncanbeusedtosavesomenetworktraffic.

HeaderParameters

If-Match(optional):Youcanconditionallyreplaceadocumentbasedonatargetrevisionidbyusingtheif-matchHTTPheader.

Replacesthedocumentwithhandlewiththeoneinthebody,providedthereissuchadocumentandnopreconditionisviolated.

IftheIf-Matchheaderisspecifiedandtherevisionofthedocumentinthedatabaseisunequaltothegivenrevision,thepreconditionisviolated.

IfIf-MatchisnotgivenandignoreRevsisfalseandthereisa_revattributeinthebodyanditsvaluedoesnotmatchtherevisionofthedocumentinthedatabase,thepreconditionisviolated.

Ifapreconditionisviolated,anHTTP412isreturned.

Ifthedocumentexistsandcanbeupdated,thenanHTTP201oranHTTP202isreturned(dependingonwaitForSync,seebelow),theEtagheaderfieldcontainsthenewrevisionofthedocumentandtheLocationheadercontainsacompleteURLunderwhichthedocumentcanbequeried.

Optionally,thequeryparameterwaitForSynccanbeusedtoforcesynchronizationofthedocumentreplacementoperationtodiskevenincasethatthewaitForSyncflaghadbeendisabledfortheentirecollection.Thus,thewaitForSyncqueryparametercanbeusedtoforcesynchronizationofjustspecificoperations.Tousethis,setthewaitForSyncparametertotrue.IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.

Ifsilentisnotsettotrue,thebodyoftheresponsecontainsaJSONobjectwiththeinformationaboutthehandleandtherevision.Theattribute_idcontainstheknowndocument-handleoftheupdateddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthenewdocumentrevision.

IfthequeryparameterreturnOldistrue,thenthecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.

IfthequeryparameterreturnNewistrue,thenthecompletenewdocumentisreturnedunderthenewattributeintheresult.

Ifthedocumentdoesnotexist,thenaHTTP404isreturnedandthebodyoftheresponsecontainsanerrordocument.

Example:Usingadocumenthandle

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/document/products/11134<<EOF

{"Hello":"you"}

HTTP/1.1202Accepted

etag:"_WQ47Yd6--A"

"_key":"11134",

"_rev":"_WQ47Yd6--A",

"_oldRev":"_WQ47Yd6---"

Example:Unknowndocumenthandle

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/document/products/11170<<EOF

HTTP/1.1404NotFound

"error":true,

"errorMessage":"documentnotfound",

"code":404,

"errorNum":1202

Example:Producearevisionconflict

shell>curl-XPUT--header'If-Match:"_WQ47YfG--B"'--data-binary@---dump-http://localhost:8529/_api/document/products/11

151<<EOF

{"other":"content"}

HTTP/1.1412PreconditionFailed

etag:"_WQ47YfG--_"

"error":true,

"code":412,

"errorNum":1200,

"errorMessage":"preconditionfailed",

"_key":"11151",

"_rev":"_WQ47YfG--_"

ReturnCodes

201:isreturnedifthedocumentwasreplacedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentwasreplacedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofadocument.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionorthedocumentwasnotfound.412:isreturnedifthepreconditionwasviolated.Theresponsewillalsocontainthefounddocuments'currentrevisionsinthe_revattributes.Additionally,theattributes_idand_keywillbereturned.

Examples

Usingadocumenthandle

http://localhost:8529/_api/document/products/11134<<EOF

{"Hello":"you"}

HTTP/1.1202Accepted

etag:"_WQ47Yd6--A"

showresponsebodyUnknowndocumenthandle

HTTP/1.1404NotFound

showresponsebodyProducearevisionconflict

shell>curl-XPUT--header'If-Match:"_WQ47YfG--B"'--data-binary@---dump-

{"other":"content"}

etag:"_WQ47YfG--_"

showresponsebody

TherearequitesomechangesinthisincomparisontoVersion2.8,butfewbreakexistingusage:

therevqueryparameterisgone(wasduplicationofIf-Match)thepolicyqueryparameterisgone(wasnon-sensical)theignoreRevsqueryparameterisnew,thedefaulttruegivesthetraditionalbehaviorasin2.8thereturnNewandreturnOldqueryparametersarenew

Thereshouldbeveryfewchangestobehaviorhappeninginreal-worldsituationsordrivers.Essentially,onehastoreplaceusageoftherevqueryparameterbyusageoftheIf-Matchheader.Thenon-sensicalcombinationofIf-Matchgivenandpolicy=lastnolongerworks,butcaneasilybeachievedbyleavingouttheIf-Matchheader.

Replacedocuments

replacesmultipledocuments

PUT/_api/document/{collection}

AJSONrepresentationofanarrayofdocuments.

PathParameters

collection(required):ThisURLparameteristhenameofthecollectioninwhichthedocumentsarereplaced.

QueryParameters

waitForSync(optional):Waituntilthenewdocumentshavebeensyncedtodisk.ignoreRevs(optional):Bydefault,orifthisissettotrue,the_revattributesinthegivendocumentsareignored.Ifthisissettofalse,thenany_revattributegiveninabodydocumentistakenasaprecondition.Thedocumentisonlyreplacedifthecurrentrevisionistheonespecified.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentsundertheattributeoldintheresult.returnNew(optional):Returnadditionallythecompletenewdocumentsundertheattributenewintheresult.

Replacesmultipledocumentsinthespecifiedcollectionwiththeonesinthebody,thereplaceddocumentsarespecifiedbythe_keyattributesinthebodydocuments.

IfignoreRevsisfalseandthereisa_revattributeinadocumentinthebodyanditsvaluedoesnotmatchtherevisionofthecorrespondingdocumentinthedatabase,thepreconditionisviolated.

Ifthedocumentexistsandcanbeupdated,thenanHTTP201oranHTTP202isreturned(dependingonwaitForSync,seebelow).

ThebodyoftheresponsecontainsaJSONarrayofthesamelengthastheinputarraywiththeinformationaboutthehandleandtherevisionofthereplaceddocuments.Ineachentry,theattribute_idcontainstheknowndocument-handleofeachupdateddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthenewdocumentrevision.Incaseofanerrororviolatedprecondition,anerrorobjectwiththeattributeerrorsettotrueandtheattributeerrorCodesettotheerrorcodeisbuilt.

IfthequeryparameterreturnOldistrue,then,foreachgenerateddocument,thecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.

Notethatifanypreconditionisviolatedoranerroroccurredwithsomeofthedocuments,thereturncodeisstill201or202,buttheadditionalHTTPheaderX-Arango-Error-Codesisset,whichcontainsamapoftheerrorcodesthatoccurredtogetherwiththeirmultiplicities,asin:1200:17,1205:10whichmeansthatin17casestheerror1200"revisionconflict"andin10casestheerror1205"illegaldocumenthandle"hashappened.

ReturnCodes

201:isreturnedifthedocumentswerereplacedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentswerereplacedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofanarrayofdocuments.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionwasnotfound.

Themultidocumentversionisnewin3.0.

Updatedocument

updatesadocument

PATCH/_api/document/{document-handle}

AJSONrepresentationofadocumentupdateasanobject.

PathParameters

document-handle(required):ThisURLparametermustbeadocumenthandle.

QueryParameters

keepNull(optional):Iftheintentionistodeleteexistingattributeswiththepatchcommand,theURLqueryparameterkeepNullcanbeusedwithavalueoffalse.Thiswillmodifythebehaviorofthepatchcommandtoremoveanyattributesfromtheexistingdocumentthatarecontainedinthepatchdocumentwithanattributevalueofnull.mergeObjects(optional):Controlswhetherobjects(notarrays)willbemergedifpresentinboththeexistingandthepatchdocument.Ifsettofalse,thevalueinthepatchdocumentwilloverwritetheexistingdocument'svalue.Ifsettotrue,objectswillbemerged.Thedefaultistrue.waitForSync(optional):Waituntildocumenthasbeensyncedtodisk.ignoreRevs(optional):Bydefault,orifthisissettotrue,the_revattributesinthegivendocumentisignored.Ifthisissettofalse,thenthe_revattributegiveninthebodydocumentistakenasaprecondition.Thedocumentisonlyupdatedifthecurrentrevisionistheonespecified.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentundertheattributeoldintheresult.returnNew(optional):Returnadditionallythecompletenewdocumentundertheattributenewintheresult.silent(optional):Ifsettotrue,anemptyobjectwillbereturnedasresponse.Nometa-datawillbereturnedfortheupdateddocument.Thisoptioncanbeusedtosavesomenetworktraffic.

HeaderParameters

If-Match(optional):Youcanconditionallyupdateadocumentbasedonatargetrevisionidbyusingtheif-matchHTTPheader.

Partiallyupdatesthedocumentidentifiedbydocument-handle.ThebodyoftherequestmustcontainaJSONdocumentwiththeattributestopatch(thepatchdocument).Allattributesfromthepatchdocumentwillbeaddedtotheexistingdocumentiftheydonotyetexist,andoverwrittenintheexistingdocumentiftheydoexistthere.

Settinganattributevaluetonullinthepatchdocumentwillcauseavalueofnulltobesavedfortheattributebydefault.

IftheIf-Matchheaderisspecifiedandtherevisionofthedocumentinthedatabaseisunequaltothegivenrevision,thepreconditionisviolated.

IfIf-MatchisnotgivenandignoreRevsisfalseandthereisa_revattributeinthebodyanditsvaluedoesnotmatchtherevisionofthedocumentinthedatabase,thepreconditionisviolated.

Ifapreconditionisviolated,anHTTP412isreturned.

Ifthedocumentexistsandcanbeupdated,thenanHTTP201oranHTTP202isreturned(dependingonwaitForSync,seebelow),theEtagheaderfieldcontainsthenewrevisionofthedocument(indoublequotes)andtheLocationheadercontainsacompleteURLunderwhichthedocumentcanbequeried.

Optionally,thequeryparameterwaitForSynccanbeusedtoforcesynchronizationoftheupdateddocumentoperationtodiskevenincasethatthewaitForSyncflaghadbeendisabledfortheentirecollection.Thus,thewaitForSyncqueryparametercanbeusedtoforcesynchronizationofjustspecificoperations.Tousethis,setthewaitForSyncparametertotrue.IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.

Ifsilentisnotsettotrue,thebodyoftheresponsecontainsaJSONobjectwiththeinformationaboutthehandleandtherevision.Theattribute_idcontainstheknowndocument-handleoftheupdateddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthenewdocumentrevision.

IfthequeryparameterreturnNewistrue,thenthecompletenewdocumentisreturnedunderthenewattributeintheresult.

Ifthedocumentdoesnotexist,thenaHTTP404isreturnedandthebodyoftheresponsecontainsanerrordocument.

Example:Patchesanexistingdocumentwithnewcontent.

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10905<<EOF

"hello":"world"

HTTP/1.1202Accepted

etag:"_WQ47YN6--B"

"_key":"10905",

"_rev":"_WQ47YN6--B",

"_oldRev":"_WQ47YN6--_"

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10905<<EOF

"numbers":{

"one":1,

"two":2,

"three":3,

"empty":null

HTTP/1.1202Accepted

etag:"_WQ47YO---_"

"_key":"10905",

"_rev":"_WQ47YO---_",

"_oldRev":"_WQ47YN6--B"

HTTP/1.1200OK

etag:"_WQ47YO---_"

"_key":"10905",

"_rev":"_WQ47YO---_",

"one":"world",

"hello":"world",

"numbers":{

"one":1,

"two":2,

"three":3,

"empty":null

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10905?keepNull=false<<EOF

"hello":null,

"numbers":{

"four":4

HTTP/1.1202Accepted

etag:"_WQ47YOG--_"

"_key":"10905",

"_rev":"_WQ47YOG--_",

"_oldRev":"_WQ47YO---_"

HTTP/1.1200OK

etag:"_WQ47YOG--_"

"_key":"10905",

"_rev":"_WQ47YOG--_",

"one":"world",

"numbers":{

"empty":null,

"one":1,

"three":3,

"two":2,

"four":4

Example:MergingattributesofanobjectusingmergeObjects:

HTTP/1.1200OK

etag:"_WQ47YPK--_"

"_key":"10928",

"_rev":"_WQ47YPK--_",

"inhabitants":{

"china":1366980000,

"india":1263590000,

"usa":319220000

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10928?mergeObjects=true<<EOF

"inhabitants":{

"indonesia":252164800,

"brazil":203553000

HTTP/1.1200OK

etag:"_WQ47YPS---"

"_key":"10928",

"_rev":"_WQ47YPS---",

"inhabitants":{

"china":1366980000,

"india":1263590000,

"usa":319220000,

"indonesia":252164800,

"brazil":203553000

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/document/products/10928?mergeObjects=false<<EOF

"inhabitants":{

"pakistan":188346000

HTTP/1.1202Accepted

etag:"_WQ47YPa--_"

"_key":"10928",

"_rev":"_WQ47YPa--_",

"_oldRev":"_WQ47YPS---"

HTTP/1.1200OK

etag:"_WQ47YPa--_"

"_key":"10928",

"_rev":"_WQ47YPa--_",

"inhabitants":{

"pakistan":188346000

ReturnCodes

201:isreturnedifthedocumentwasupdatedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentwasupdatedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofadocument.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionorthedocumentwasnotfound.412:isreturnedifthepreconditionwasviolated.Theresponsewillalsocontainthefounddocuments'currentrevisionsinthe_revattributes.Additionally,theattributes_idand_keywillbereturned.

Examples

Patchesanexistingdocumentwithnewcontent.

shell>curl-XPATCH--data-binary@---dump-

"hello":"world"

HTTP/1.1202Accepted

etag:"_WQ47YN6--B"

showresponsebodyMergingattributesofanobjectusingmergeObjects:

HTTP/1.1200OK

etag:"_WQ47YPK--_"

showresponsebody

TherearequitesomechangesinthisincomparisontoVersion2.8,butfewbreakexistingusage:

therevqueryparameterisgone(wasduplicationofIf-Match)thepolicyqueryparameterisgone(wasnon-sensical)theignoreRevsqueryparameterisnew,thedefaulttruegivesthetraditionalbehaviorasin2.8thereturnNewandreturnOldqueryparametersarenew

Updatedocuments

updatesmultipledocuments

PATCH/_api/document/{collection}

AJSONrepresentationofanarrayofdocumentupdatesasobjects.

PathParameters

collection(required):ThisURLparameteristhenameofthecollectioninwhichthedocumentsareupdated.

QueryParameters

keepNull(optional):Iftheintentionistodeleteexistingattributeswiththepatchcommand,theURLqueryparameterkeepNullcan

beusedwithavalueoffalse.Thiswillmodifythebehaviorofthepatchcommandtoremoveanyattributesfromtheexistingdocumentthatarecontainedinthepatchdocumentwithanattributevalueofnull.mergeObjects(optional):Controlswhetherobjects(notarrays)willbemergedifpresentinboththeexistingandthepatchdocument.Ifsettofalse,thevalueinthepatchdocumentwilloverwritetheexistingdocument'svalue.Ifsettotrue,objectswillbemerged.Thedefaultistrue.waitForSync(optional):Waituntilthenewdocumentshavebeensyncedtodisk.ignoreRevs(optional):Bydefault,orifthisissettotrue,the_revattributesinthegivendocumentsareignored.Ifthisissettofalse,thenany_revattributegiveninabodydocumentistakenasaprecondition.Thedocumentisonlyupdatedifthecurrentrevisionistheonespecified.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentsundertheattributeoldintheresult.returnNew(optional):Returnadditionallythecompletenewdocumentsundertheattributenewintheresult.

Partiallyupdatesdocuments,thedocumentstoupdatearespecifiedbythe_keyattributesinthebodyobjects.ThebodyoftherequestmustcontainaJSONarrayofdocumentupdateswiththeattributestopatch(thepatchdocuments).Allattributesfromthepatchdocumentswillbeaddedtotheexistingdocumentsiftheydonotyetexist,andoverwrittenintheexistingdocumentsiftheydoexistthere.

Settinganattributevaluetonullinthepatchdocumentswillcauseavalueofnulltobesavedfortheattributebydefault.

IfignoreRevsisfalseandthereisa_revattributeinadocumentinthebodyanditsvaluedoesnotmatchtherevisionofthecorrespondingdocumentinthedatabase,thepreconditionisviolated.

Ifthedocumentexistsandcanbeupdated,thenanHTTP201oranHTTP202isreturned(dependingonwaitForSync,seebelow).

ThebodyoftheresponsecontainsaJSONarrayofthesamelengthastheinputarraywiththeinformationaboutthehandleandtherevisionoftheupdateddocuments.Ineachentry,theattribute_idcontainstheknowndocument-handleofeachupdateddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthenewdocumentrevision.Incaseofanerrororviolatedprecondition,anerrorobjectwiththeattributeerrorsettotrueandtheattributeerrorCodesettotheerrorcodeisbuilt.

IfthequeryparameterreturnOldistrue,then,foreachgenerateddocument,thecompletepreviousrevisionofthedocumentisreturnedundertheoldattributeintheresult.

ReturnCodes

201:isreturnedifthedocumentswereupdatedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentswereupdatedsuccessfullyandwaitForSyncwasfalse.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofanarrayofdocuments.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionwasnotfound.

Themultidocumentversionisnewin3.0.

Removesadocument

removesadocument

DELETE/_api/document/{document-handle}

PathParameters

document-handle(required):Removesthedocumentidentifiedbydocument-handle.

QueryParameters

waitForSync(optional):Waituntildeletionoperationhasbeensyncedtodisk.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentundertheattributeoldintheresult.silent(optional):Ifsettotrue,anemptyobjectwillbereturnedasresponse.Nometa-datawillbereturnedfortheremoveddocument.Thisoptioncanbeusedtosavesomenetworktraffic.

HeaderParameters

If-Match(optional):Youcanconditionallyremoveadocumentbasedonatargetrevisionidbyusingtheif-matchHTTPheader.

Ifsilentisnotsettotrue,thebodyoftheresponsecontainsaJSONobjectwiththeinformationaboutthehandleandtherevision.Theattribute_idcontainstheknowndocument-handleoftheremoveddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthedocumentrevision.

IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.

Example:Usingdocumenthandle:

shell>curl-XDELETE--dump-http://localhost:8529/_api/document/products/10788

HTTP/1.1200OK

etag:"_WQ47YCu--_"

"_key":"10788",

"_rev":"_WQ47YCu--_"

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":1202

Example:Revisionconflict:

shell>curl-XDELETE--header'If-Match:"_WQ47YEu--B"'--dump-http://localhost:8529/_api/document/products/10805

etag:"_WQ47YEu--_"

"error":true,

"code":412,

"errorNum":1200,

"_key":"10805",

"_rev":"_WQ47YEu--_"

ReturnCodes

200:isreturnedifthedocumentwasremovedsuccessfullyandwaitForSyncwastrue.202:isreturnedifthedocumentwasremovedsuccessfullyandwaitForSyncwasfalse.404:isreturnedifthecollectionorthedocumentwasnotfound.Theresponsebodycontainsanerrordocumentinthiscase.412:isreturnedifa"If-Match"headerorrevisgivenandthefounddocumenthasadifferentversion.Theresponsewillalsocontainthefounddocument'scurrentrevisioninthe_revattribute.Additionally,theattributes_idand_keywillbereturned.

Examples

Usingdocumenthandle:

HTTP/1.1200OK

etag:"_WQ47YCu--_"

showresponsebodyUnknowndocumenthandle:

HTTP/1.1404NotFound

showresponsebodyRevisionconflict:

shell>curl-XDELETE--header'If-Match:"_WQ47YEu--B"'--dump-

etag:"_WQ47YEu--_"

showresponsebody

ThereareonlyveryfewchangesinthisincomparisontoVersion2.8:

therevqueryparameterisgone(wasduplicationofIf-Match)thepolicyqueryparameterisgone(wasnon-sensical)thereturnOldqueryparameterisnew

Removesmultipledocuments

removesmultipledocument

DELETE/_api/document/{collection}

AJSONarrayofstringsordocuments.

PathParameters

collection(required):Collectionfromwhichdocumentsareremoved.

QueryParameters

waitForSync(optional):Waituntildeletionoperationhasbeensyncedtodisk.returnOld(optional):Returnadditionallythecompletepreviousrevisionofthechangeddocumentundertheattributeoldintheresult.ignoreRevs(optional):Ifsettotrue,ignoreany_revattributeintheselectors.Norevisioncheckisperformed.

Thebodyoftherequestisanarrayconsistingofselectorsfordocuments.Aselectorcaneitherbeastringwithakeyorastringwithadocumenthandleoranobjectwitha_keyattribute.ThisAPIcallremovesallspecifieddocumentsfromcollection.Iftheselectorisanobjectandhasa_revattribute,itisapreconditionthattheactualrevisionoftheremoveddocumentinthecollectionisthespecifiedone.

Thebodyoftheresponseisanarrayofthesamelengthastheinputarray.Foreachinputselector,theoutputcontainsaJSONobjectwiththeinformationabouttheoutcomeoftheoperation.Ifnoerroroccurred,anobjectisbuiltinwhichtheattribute_idcontainstheknowndocument-handleoftheremoveddocument,_keycontainsthekeywhichuniquelyidentifiesadocumentinagivencollection,andtheattribute_revcontainsthedocumentrevision.Incaseofanerror,anobjectwiththeattributeerrorsettotrueanderrorCodesettotheerrorcodeisbuilt.

IfthewaitForSyncparameterisnotspecifiedorsettofalse,thenthecollection'sdefaultwaitForSyncbehaviorisapplied.ThewaitForSyncqueryparametercannotbeusedtodisablesynchronizationforcollectionsthathaveadefaultwaitForSyncvalueoftrue.

Example:

HTTP/1.1200OK

etag:"_WQ47YHa--_"

"_key":"10843",

"_rev":"_WQ47YHa--_"

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":1202

Example:Revisionconflict:

shell>curl-XDELETE--header'If-Match:"_WQ47YFO--_"'--dump-http://localhost:8529/_api/document/products/10824

etag:"_WQ47YFK--_"

"error":true,

"code":412,

"errorNum":1200,

"_key":"10824",

"_rev":"_WQ47YFK--_"

ReturnCodes

200:isreturnedifwaitForSyncwastrue.202:isreturnedifwaitForSyncwasfalse.404:isreturnedifthecollectionwasnotfound.Theresponsebodycontainsanerrordocumentinthiscase.

Examples

HTTP/1.1200OK

etag:"_WQ47YHa--_"

showresponsebodyUnknowndocumenthandle:

HTTP/1.1404NotFound

showresponsebodyRevisionconflict:

shell>curl-XDELETE--header'If-Match:"_WQ47YFO--_"'--dump-

etag:"_WQ47YFK--_"

showresponsebody

Thisvariantisnewin3.0.NotethatitrequiresabodyintheDELETErequest.

HTTPInterfaceforEdgesThisisanintroductiontoArangoDB'sRESTinterfaceforedges.

ArangoDBoffersgraphfunctionality;Edgesareonepartofthat.

AddressandEtagofanEdgeAlldocumentsinArangoDBhaveadocumenthandle.Thishandleuniquelyidentifiesadocument.AnydocumentcanberetrievedusingitsuniqueURI:

Edgesareaspecialvariationofdocuments.ToaccessanedgeusethesameURLformatasforadocument:

Forexample,assumedthatthedocumenthandle,whichisstoredinthe_idattributeoftheedge,isdemo/362549736,thentheURLofthatedgeis:

http://localhost:8529/_api/document/demo/362549736

TheaboveURLschemedoesnotspecifyadatabasenameexplicitly,sothedefaultdatabasewillbeused.Toexplicitlyspecifythedatabasecontext,usethefollowingURLschema:

http://server:port/_db/<database-name>/_api/document/<document-handle>

Example:

http://localhost:8529/_db/mydb/_api/document/demo/362549736

Note:thatthefollowingexamplesusetheshortURLformatforbrevity.

AddressandEtag

WorkingwithEdgesusingRESTThisisdocumentationtoArangoDB'sRESTinterfaceforedges.

Edgesaredocumentswithtwoadditionalattributes:_fromand_to.Theseattributesaremandatoryandmustcontainthedocument-handleofthefromandtoverticesofanedge.

UsethegeneraldocumentRESTapiforcreate/read/update/delete.

Readin-oroutboundedges

getedges

GET/_api/edges/{collection-id}

PathParameters

collection-id(required):Theidofthecollection.

QueryParameters

vertex(required):Theidofthestartvertex.direction(optional):Selectsinoroutdirectionforedges.Ifnotset,anyedgesarereturned.

Returnsanarrayofedgesstartingorendinginthevertexidentifiedbyvertex-handle.

Example:Anydirection

shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1

HTTP/1.1200OK

"edges":[

"_key":"6",

"_id":"edges/6",

"_from":"vertices/2",

"_to":"vertices/1",

"_rev":"_WQ47Ygy---",

"$label":"v2->v1"

"_key":"7",

"_id":"edges/7",

"_to":"vertices/1",

"_rev":"_WQ47Ygy--A",

"$label":"v4->v1"

"_key":"5",

"_id":"edges/5",

"_to":"vertices/3",

"_rev":"_WQ47Ygu--H",

"$label":"v1->v3"

"error":false,

"code":200,

"stats":{

"scannedIndex":3,

WorkingwithEdges

"filtered":0

Example:Inedges

shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=in

HTTP/1.1200OK

"edges":[

"_key":"6",

"_id":"edges/6",

"_to":"vertices/1",

"_rev":"_WQ47Yj---_",

"$label":"v2->v1"

"_key":"7",

"_id":"edges/7",

"_to":"vertices/1",

"_rev":"_WQ47Yj---B",

"$label":"v4->v1"

"error":false,

"code":200,

"stats":{

"scannedIndex":2,

"filtered":0

Example:Outedges

shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=out

HTTP/1.1200OK

"edges":[

"_key":"5",

"_id":"edges/5",

"_to":"vertices/3",

"_rev":"_WQ47Yjy--H",

"$label":"v1->v3"

"error":false,

"code":200,

"stats":{

"scannedIndex":1,

"filtered":0

WorkingwithEdges

ReturnCodes

200:isreturnediftheedgecollectionwasfoundandedgeswereretrieved.400:isreturnediftherequestcontainsinvalidparameters.404:isreturnediftheedgecollectionwasnotfound.

Examples

Anydirection

shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1

HTTP/1.1200OK

showresponsebodyInedges

shell>curl--dump-http://localhost:8529/_api/edges/edges?vertex=vertices/1&direction=in

HTTP/1.1200OK

showresponsebodyOutedges

shell>curl--dump-http://localhost:8529/_api/edges/edges?

vertex=vertices/1&direction=out

HTTP/1.1200OK

showresponsebody

WorkingwithEdges

GeneralGraphsThischapterdescribestheRESTinterfaceforthemulti-collectiongraphmodule.Itallowsyoutodefineagraphthatisspreadacrossseveraledgeanddocumentcollections.Thereisnoneedtoincludethereferencedcollectionswithinthequery,thismodulewillhandleitforyou.

GeneralGraph

ManageyourgraphsThegraphmoduleprovidesfunctionsdealingwithgraphstructures.ExampleswillexplaintheRESTAPIonthesocialgraph:

Listallgraphs

Listsallgraphsknowntothegraphmodule.

GET/_api/gharial

Listsallgraphnamesstoredinthisdatabase.

Example:

shell>curl--dump-http://localhost:8529/_api/gharial

HTTP/1.1200OK

"error":false,

"graphs":[

"_key":"routeplanner",

"_id":"_graphs/routeplanner",

"_rev":"_WQ47RH2--_",

"orphanCollections":[],

"edgeDefinitions":[

"collection":"germanHighway",

"from":[

"germanCity"

"to":[

"germanCity"

"collection":"frenchHighway",

"from":[

"frenchCity"

"to":[

"frenchCity"

"collection":"internationalHighway",

"from":[

"frenchCity",

"germanCity"

"to":[

"frenchCity",

"germanCity"

"numberOfShards":1,

"replicationFactor":1

"_key":"social",

"_id":"_graphs/social",

"_rev":"_WQ47Q8C--_",

Management

"edgeDefinitions":[

"collection":"relation",

"from":[

"female",

"male"

"to":[

"female",

"male"

"numberOfShards":1,

"replicationFactor":1

"code":200

ReturnCodes

200:Isreturnedifthemoduleisavailableandthegraphscouldbelisted.

Examples

shell>curl--dump-http://localhost:8529/_api/gharial

HTTP/1.1200OK

showresponsebody

Createagraph

Createanewgraphinthegraphmodule.

POST/_api/gharial

Thecreationofagraphrequiresthenameofthegraphandadefinitionofitsedges.Seealsoedgedefinitions.

orphanCollections:Anarrayofadditionalvertexcollections.edgeDefinitions:Anarrayofdefinitionsfortheedgename:Nameofthegraph.isSmart:Defineifthecreatedgraphshouldbesmart.ThisonlyhaseffectinEnterpriseversion.options:

smartGraphAttribute:Theattributenamethatisusedtosmartlyshardtheverticesofagraph.EveryvertexinthisGraphhastohavethisattribute.Cannotbemodifiedlater.numberOfShards:Thenumberofshardsthatisusedforeverycollectionwithinthisgraph.Cannotbemodifiedlater.

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial<<EOF

"name":"myGraph",

"edgeDefinitions":[

"collection":"edges",

"from":[

"startVertices"

Management

"to":[

"endVertices"

HTTP/1.1202Accepted

etag:_WQ47OnC--_

"error":false,

"graph":{

"name":"myGraph",

"edgeDefinitions":[

"from":[

"startVertices"

"to":[

"endVertices"

"isSmart":false,

"numberOfShards":0,

"replicationFactor":1,

"smartGraphAttribute":"",

"_id":"_graphs/myGraph",

"_rev":"_WQ47OnC--_"

"code":202

Example:

"name":"myGraph",

"edgeDefinitions":[

"from":[

"startVertices"

"to":[

"endVertices"

"isSmart":true,

"options":{

"numberOfShards":9,

"smartGraphAttribute":"region"

HTTP/1.1202Accepted

etag:_WQ47PHG--_

"error":false,

"graph":{

Management

"name":"myGraph",

"edgeDefinitions":[

"from":[

"startVertices"

"to":[

"endVertices"

"isSmart":false,

"numberOfShards":0,

"_rev":"_WQ47PHG--_"

"code":202

"name":"myGraph",

"edgeDefinitions":[

"from":[

"startVertices"

"to":[

"endVertices"

HTTP/1.1202Accepted

etag:_WQ47OnC--_

showresponsebody

"name":"myGraph",

"edgeDefinitions":[

"from":[

"startVertices"

"to":[

"endVertices"

Management

"isSmart":true,

"options":{

"numberOfShards":9,

"smartGraphAttribute":"region"

HTTP/1.1202Accepted

etag:_WQ47PHG--_

showresponsebody

Getagraph

Getagraphfromthegraphmodule.

GET/_api/gharial/{graph-name}

Getsagraphfromthecollection_graphs.Returnsthedefinitioncontentofthisgraph.

Example:

shell>curl--dump-http://localhost:8529/_api/gharial/myGraph

HTTP/1.1200OK

etag:_WQ47Qli--_

"error":false,

"graph":{

"name":"myGraph",

"edgeDefinitions":[

"from":[

"startVertices"

"to":[

"endVertices"

"isSmart":false,

"numberOfShards":1,

"_rev":"_WQ47Qli--_"

"code":200

PathParameters

graph-name(required):Thenameofthegraph.

ReturnCodes

Management

200:Returnedifthegraphcouldbefound.404:Returnedifnographwiththisnamecouldbefound.

Examples

shell>curl--dump-http://localhost:8529/_api/gharial/myGraph

HTTP/1.1200OK

etag:_WQ47Qli--_

showresponsebody

Dropagraph

deleteanexistinggraph

DELETE/_api/gharial/{graph-name}

Removesagraphfromthecollection_graphs.

Example:

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social?dropCollections=true

HTTP/1.1202Accepted

"error":false,

"removed":true,

"code":202

PathParameters

QueryParameters

dropCollections(optional):Dropcollectionsofthisgraphaswell.Collectionswillonlybedroppediftheyarenotusedinothergraphs.

ReturnCodes

201:IsreturnedifthegraphcouldbedroppedandwaitForSyncisenabledforthe_graphscollection.202:ReturnedifthegraphcouldbedroppedandwaitForSyncisdisabledforthe_graphscollection.404:Returnedifnographwiththisnamecouldbefound.

Examples

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social?

dropCollections=true

HTTP/1.1202Accepted

Management

showresponsebody

Listvertexcollections

Listsallvertexcollectionsusedinthisgraph.

GET/_api/gharial/{graph-name}/vertex

Listsallvertexcollectionswithinthisgraph.

Example:

shell>curl--dump-http://localhost:8529/_api/gharial/social/vertex

HTTP/1.1200OK

"error":false,

"collections":[

"female",

"male"

"code":200

PathParameters

ReturnCodes

200:Isreturnedifthecollectionscouldbelisted.404:Returnedifnographwiththisnamecouldbefound.

Examples

shell>curl--dump-http://localhost:8529/_api/gharial/social/vertex

HTTP/1.1200OK

showresponsebody

Addvertexcollection

Addanadditionalvertexcollectiontothegraph.

POST/_api/gharial/{graph-name}/vertex

Addsavertexcollectiontothesetofcollectionsofthegraph.Ifthecollectiondoesnotexist,itwillbecreated.

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial/social/vertex<<EOF

"collection":"otherVertices"

Management

HTTP/1.1202Accepted

etag:_WQ47N8y--_

"error":false,

"graph":{

"name":"social",

"edgeDefinitions":[

"from":[

"female",

"male"

"to":[

"female",

"male"

"orphanCollections":[

"otherVertices"

"isSmart":false,

"numberOfShards":1,

"_rev":"_WQ47N8y--_"

"code":202

PathParameters

ReturnCodes

201:ReturnediftheedgecollectioncouldbeaddedsuccessfullyandwaitForSyncistrue.202:ReturnediftheedgecollectioncouldbeaddedsuccessfullyandwaitForSyncisfalse.404:Returnedifnographwiththisnamecouldbefound.

Examples

http://localhost:8529/_api/gharial/social/vertex<<EOF

"collection":"otherVertices"

HTTP/1.1202Accepted

etag:_WQ47N8y--_

showresponsebody

Removevertexcollection

Removeavertexcollectionformthegraph.

Management

DELETE/_api/gharial/{graph-name}/vertex/{collection-name}

Removesavertexcollectionfromthegraphandoptionallydeletesthecollection,ifitisnotusedinanyothergraph.

Example:Youcanremovevertexcollectionsthatarenotusedinanyedgecollection:

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/vertex/otherVertices

HTTP/1.1202Accepted

etag:_WQ47T_e--_

"error":false,

"graph":{

"name":"social",

"edgeDefinitions":[

"from":[

"female",

"male"

"to":[

"female",

"male"

"isSmart":false,

"numberOfShards":1,

"_rev":"_WQ47T_e--_"

"code":202

Example:Youcannotremovevertexcollectionsthatareusedinedgecollections:

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/vertex/male

"error":true,

"errorNum":1928,

"errorMessage":"notinorphancollection",

"code":400

PathParameters

graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollection.

QueryParameters

Management

dropCollection(optional):Dropthecollectionaswell.Collectionwillonlybedroppedifitisnotusedinothergraphs.

ReturnCodes

201:ReturnedifthevertexcollectionwasremovedfromthegraphsuccessfullyandwaitForSyncistrue.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.400:Returnedifthevertexcollectionisstillusedinanedgedefinition.Inthiscaseitcannotberemovedfromthegraphyet,ithastoberemovedfromtheedgedefinitionfirst.404:Returnedifnographwiththisnamecouldbefound.

Examples

Youcanremovevertexcollectionsthatarenotusedinanyedgecollection:

shell>curl-XDELETE--dump-

http://localhost:8529/_api/gharial/social/vertex/otherVertices

HTTP/1.1202Accepted

etag:_WQ47T_e--_

showresponsebodyYoucannotremovevertexcollectionsthatareusedinedgecollections:

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/vertex/male

showresponsebody

Listedgedefinitions

Listsalledgedefinitions

GET/_api/gharial/{graph-name}/edge

Listsalledgecollectionswithinthisgraph.

Example:

shell>curl--dump-http://localhost:8529/_api/gharial/social/edge

HTTP/1.1200OK

"error":false,

"collections":[

"relation"

"code":200

PathParameters

Management

ReturnCodes

200:Isreturnediftheedgedefinitionscouldbelisted.404:Returnedifnographwiththisnamecouldbefound.

Examples

shell>curl--dump-http://localhost:8529/_api/gharial/social/edge

HTTP/1.1200OK

showresponsebody

Addedgedefinition

Addanewedgedefinitiontothegraph

POST/_api/gharial/{graph-name}/edge

Addsanadditionaledgedefinitiontothegraph.

Thisedgedefinitionhastocontainacollectionandanarrayofeachfromandtovertexcollections.Anedgedefinitioncanonlybeaddedifthisdefinitioniseithernotusedinanyothergraph,oritisusedwithexactlythesamedefinition.Itisnotpossibletostoreadefinition"e"from"v1"to"v2"intheonegraph,and"e"from"v2"to"v1"intheothergraph.

to(string):Oneormanyvertexcollectionsthatcancontaintargetvertices.from(string):Oneormanyvertexcollectionsthatcancontainsourcevertices.collection:Thenameoftheedgecollectiontobeused.

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge<<EOF

"collection":"works_in",

"from":[

"female",

"male"

"to":[

"city"

HTTP/1.1202Accepted

etag:_WQ47Mr6--_

"error":false,

"graph":{

"name":"social",

"edgeDefinitions":[

"from":[

"female",

"male"

Management

"to":[

"female",

"male"

"from":[

"female",

"male"

"to":[

"city"

"isSmart":false,

"numberOfShards":1,

"_rev":"_WQ47Mr6--_"

"code":202

PathParameters

ReturnCodes

201:ReturnedifthedefinitioncouldbeaddedsuccessfullyandwaitForSyncisenabledforthe_graphscollection.202:ReturnedifthedefinitioncouldbeaddedsuccessfullyandwaitForSyncisdisabledforthe_graphscollection.400:Returnedifthedefininitioncouldnotbeadded,theedgecollectionisusedinanothergraphwithadifferentsignature.404:Returnedifnographwiththisnamecouldbefound.

Examples

http://localhost:8529/_api/gharial/social/edge<<EOF

"from":[

"female",

"male"

"to":[

"city"

HTTP/1.1202Accepted

etag:_WQ47Mr6--_

showresponsebody

Replaceanedgedefinition

Management

Replaceanexistingedgedefinition

PUT/_api/gharial/{graph-name}/edge/{definition-name}

Changeonespecificedgedefinition.Thiswillmodifyalloccurrencesofthisdefinitioninallgraphsknowntoyourdatabase.

to(string):Oneormanyvertexcollectionsthatcancontaintargetvertices.from(string):Oneormanyvertexcollectionsthatcancontainsourcevertices.collection:Thenameoftheedgecollectiontobeused.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge/relation<<EOF

"from":[

"female",

"male",

"animal"

"to":[

"female",

"male",

"animal"

HTTP/1.1202Accepted

etag:_WQ47TS6--_

"error":false,

"graph":{

"name":"social",

"edgeDefinitions":[

"from":[

"animal",

"female",

"male"

"to":[

"animal",

"female",

"male"

"isSmart":false,

"numberOfShards":1,

"_rev":"_WQ47TS6--_"

"code":202

PathParameters

graph-name(required):Thenameofthegraph.definition-name(required):Thenameoftheedgecollectionusedinthedefinition.

ReturnCodes

Management

201:ReturnediftherequestwassuccessfulandwaitForSyncistrue.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.400:Returnedifnoedgedefinitionwiththisnameisfoundinthegraph.404:Returnedifnographwiththisnamecouldbefound.

Examples

http://localhost:8529/_api/gharial/social/edge/relation<<EOF

"from":[

"female",

"male",

"animal"

"to":[

"female",

"male",

"animal"

HTTP/1.1202Accepted

etag:_WQ47TS6--_

showresponsebody

Removeanedgedefinitionfromthegraph

Removeanedgedefinitionformthegraph

DELETE/_api/gharial/{graph-name}/edge/{definition-name}

Removeoneedgedefinitionfromthegraph.Thiswillonlyremovetheedgecollection,thevertexcollectionsremainuntouchedandcanstillbeusedinyourqueries.

Example:

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/edge/relation

HTTP/1.1202Accepted

etag:_WQ47QNS--_

"error":false,

"graph":{

"name":"social",

"edgeDefinitions":[],

"orphanCollections":[

"female",

"male"

"isSmart":false,

"numberOfShards":1,

Management

"_rev":"_WQ47QNS--_"

"code":202

PathParameters

graph-name(required):Thenameofthegraph.definition-name(required):Thenameoftheedgecollectionusedinthedefinition.

QueryParameters

dropCollection(optional):Dropthecollectionaswell.Collectionwillonlybedroppedifitisnotusedinothergraphs.

ReturnCodes

201:ReturnediftheedgedefinitioncouldberemovedfromthegraphandwaitForSyncistrue.202:ReturnediftheedgedefinitioncouldberemovedfromthegraphandwaitForSyncisfalse.400:Returnedifnoedgedefinitionwiththisnameisfoundinthegraph.404:Returnedifnographwiththisnamecouldbefound.

Examples

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/edge/relation

HTTP/1.1202Accepted

etag:_WQ47QNS--_

showresponsebody

Management

HandlingVerticesExampleswillexplaintheRESTAPItothegraphmoduleonthesocialgraph:

Createavertex

createanewvertex

POST/_api/gharial/{graph-name}/vertex/{collection-name}

Addsavertextothegivencollection.

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial/social/vertex/male<<EOF

"name":"Francis"

HTTP/1.1202Accepted

etag:_WQ47NdC--_

"error":false,

"vertex":{

"_id":"male/8068",

"_key":"8068",

"_rev":"_WQ47NdC--_"

"code":202

PathParameters

graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollectionthevertexbelongsto.

QueryParameters

waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.

ThebodyhastobetheJSONobjecttobestored.

ReturnCodes

201:ReturnedifthevertexcouldbeaddedandwaitForSyncistrue.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographornovertexcollectionwiththisnamecouldbefound.

Examples

http://localhost:8529/_api/gharial/social/vertex/male<<EOF

"name":"Francis"

Vertices

HTTP/1.1202Accepted

etag:_WQ47NdC--_

showresponsebody

Getavertex

fetchesanexistingvertex

GET/_api/gharial/{graph-name}/vertex/{collection-name}/{vertex-key}

Getsavertexfromthegivencollection.

Example:

shell>curl--dump-http://localhost:8529/_api/gharial/social/vertex/female/alice

HTTP/1.1200OK

etag:_WQ47Qx6--_

"error":false,

"vertex":{

"_key":"alice",

"_id":"female/alice",

"_rev":"_WQ47Qx6--_",

"name":"Alice"

"code":200

PathParameters

graph-name(required):Thenameofthegraph.collection-name(required):Thenameofthevertexcollectionthevertexbelongsto.vertex-key(required):The_keyattributeofthevertex.

HeaderParameters

if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.

ReturnCodes

200:Returnedifthevertexcouldbefound.404:Returnedifnographwiththisname,novertexcollectionornovertexwiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.

Examples

shell>curl--dump-http://localhost:8529/_api/gharial/social/vertex/female/alice

HTTP/1.1200OK

Vertices

etag:_WQ47Qx6--_

showresponsebody

Modifyavertex

replaceanexistingvertex

PATCH/_api/gharial/{graph-name}/vertex/{collection-name}/{vertex-key}

Updatesthedataofthespecificvertexinthecollection.

Example:

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/gharial/social/vertex/female/alice<<EOF

"age":26

HTTP/1.1202Accepted

etag:_WQ47SSm--_

"error":false,

"vertex":{

"_key":"alice",

"_rev":"_WQ47SSm--_",

"_oldRev":"_WQ47SSa--B"

"code":202

PathParameters

QueryParameters

waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.keepNull(optional):Defineifvaluessettonullshouldbestored.Bydefaultthekeyisnotremovedfromthedocument.

HeaderParameters

if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisupdated,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.

ThebodyhastocontainaJSONobjectcontainingexactlytheattributesthatshouldbereplaced.

ReturnCodes

200:Returnedifthevertexcouldbeupdated.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,novertexcollectionornovertexwiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.

Examples

Vertices

http://localhost:8529/_api/gharial/social/vertex/female/alice<<EOF

"age":26

HTTP/1.1202Accepted

etag:_WQ47SSm--_

showresponsebody

Replaceavertex

replacesanexistingvertex

PUT/_api/gharial/{graph-name}/vertex/{collection-name}/{vertex-key}

Replacesthedataofavertexinthecollection.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/gharial/social/vertex/female/alice<<EOF

"name":"AliceCooper",

"age":26

HTTP/1.1202Accepted

etag:_WQ47TpK--_

"error":false,

"vertex":{

"_key":"alice",

"_rev":"_WQ47TpK--_",

"_oldRev":"_WQ47Toy--B"

"code":202

PathParameters

QueryParameters

HeaderParameters

Vertices

ReturnCodes

200:Returnedifthevertexcouldbereplaced.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,novertexcollectionornovertexwiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.

Examples

http://localhost:8529/_api/gharial/social/vertex/female/alice<<EOF

"name":"AliceCooper",

"age":26

HTTP/1.1202Accepted

etag:_WQ47TpK--_

showresponsebody

Removeavertex

removesavertexfromagraph

DELETE/_api/gharial/{graph-name}/vertex/{collection-name}/{vertex-key}

Removesavertexfromthecollection.

Example:

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/vertex/female/alice

HTTP/1.1202Accepted

"error":false,

"removed":true,

"code":202

PathParameters

QueryParameters

HeaderParameters

Vertices

ReturnCodes

200:Returnedifthevertexcouldberemoved.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,novertexcollectionornovertexwiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.

Examples

http://localhost:8529/_api/gharial/social/vertex/female/alice

HTTP/1.1202Accepted

showresponsebody

Vertices

HandlingEdgesExampleswillexplaintheRESTAPIformanipulatingedgesofthegraphmoduleontheknowsgraph:

Createanedge

Createsanedgeinanexistinggraph

POST/_api/gharial/{graph-name}/edge/{collection-name}

Createsanewedgeinthecollection.Withinthebodythehastocontaina_fromand_tovaluereferencingtovalidverticesinthegraph.Furthermoretheedgehastobevalidinthedefinitionofthisedgecollection.

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge/relation<<EOF

"type":"friend",

"_from":"female/alice",

"_to":"female/diana"

HTTP/1.1202Accepted

etag:_WQ47Mfu--_

"error":false,

"edge":{

"_id":"relation/7889",

"_key":"7889",

"_rev":"_WQ47Mfu--_"

"code":202

PathParameters

graph-name(required):Thenameofthegraph.collection-name(required):Thenameoftheedgecollectiontheedgebelongsto.

QueryParameters

waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk._from(required):_to(required):

ReturnCodes

201:Returnediftheedgecouldbecreated.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.

Examples

http://localhost:8529/_api/gharial/social/edge/relation<<EOF

"type":"friend",

"_to":"female/diana"

HTTP/1.1202Accepted

etag:_WQ47Mfu--_

showresponsebody

Getanedge

fetchanedge

GET/_api/gharial/{graph-name}/edge/{collection-name}/{edge-key}

Getsanedgefromthegivencollection.

Example:

shell>curl--dump-http://localhost:8529/_api/gharial/social/edge/relation/8613

HTTP/1.1200OK

etag:_WQ47QdC--D

"error":false,

"edge":{

"_key":"8613",

"_to":"male/bob",

"_rev":"_WQ47QdC--D",

"type":"married",

"vertex":"alice"

"code":200

PathParameters

graph-name(required):Thenameofthegraph.collection-name(required):Thenameoftheedgecollectiontheedgebelongsto.edge-key(required):The_keyattributeofthevertex.

HeaderParameters

if-match(optional):Ifthe"If-Match"headerisgiven,thenitmustcontainexactlyoneEtag.Thedocumentisreturned,ifithasthesamerevisionasthegivenEtag.OtherwiseaHTTP412isreturned.AsanalternativeyoucansupplytheEtaginanattributerevintheURL.

ReturnCodes

200:Returnediftheedgecouldbefound.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.

412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.

Examples

shell>curl--dump-http://localhost:8529/_api/gharial/social/edge/relation/8613

HTTP/1.1200OK

etag:_WQ47QdC--D

showresponsebodyExampleswillexplaintheAPIonthesocialgraph:

Modifyanedge

modifyanexistingedge

PATCH/_api/gharial/{graph-name}/edge/{collection-name}/{edge-key}

Updatesthedataofthespecificedgeinthecollection.

Example:

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge/relation/9263<<EOF

"since":"01.01.2001"

HTTP/1.1202Accepted

etag:_WQ47Sgy--_

"error":false,

"edge":{

"_key":"9263",

"_rev":"_WQ47Sgy--_",

"_oldRev":"_WQ47Sgm--H"

"code":202

PathParameters

QueryParameters

waitForSync(optional):Defineiftherequestshouldwaituntilsyncedtodisk.keepNull(optional):Defineifvaluessettonullshouldbestored.Bydefaultthekeyisnotremovedfromthedocument.

ThebodyhastobeaJSONobjectcontainingtheattributestobeupdated.

ReturnCodes

200:Returnediftheedgecouldbeupdated.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.

Examples

http://localhost:8529/_api/gharial/social/edge/relation/9263<<EOF

"since":"01.01.2001"

HTTP/1.1202Accepted

etag:_WQ47Sgy--_

showresponsebody

Replaceanedge

replacethecontentofanexistingedge

PUT/_api/gharial/{graph-name}/edge/{collection-name}/{edge-key}

Replacesthedataofanedgeinthecollection.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/gharial/social/edge/relation/9340<<EOF

"type":"divorced",

"_to":"male/bob"

HTTP/1.1202Accepted

etag:_WQ47SvK--_

"error":false,

"edge":{

"_key":"9340",

"_rev":"_WQ47SvK--_",

"_oldRev":"_WQ47SvC--H"

"code":202

PathParameters

QueryParameters

HeaderParameters

ReturnCodes

201:ReturnediftherequestwassuccessfulbutwaitForSyncistrue.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.

Examples

http://localhost:8529/_api/gharial/social/edge/relation/9340<<EOF

"type":"divorced",

"_to":"male/bob"

HTTP/1.1202Accepted

etag:_WQ47SvK--_

showresponsebody

Removeanedge

removesanedgefromgraph

DELETE/_api/gharial/{graph-name}/edge/{collection-name}/{edge-key}

Removesanedgefromthecollection.

Example:

shell>curl-XDELETE--dump-http://localhost:8529/_api/gharial/social/edge/relation/8310

HTTP/1.1202Accepted

"error":false,

"removed":true,

"code":202

PathParameters

QueryParameters

HeaderParameters

ReturnCodes

200:Returnediftheedgecouldberemoved.202:ReturnediftherequestwassuccessfulbutwaitForSyncisfalse.404:Returnedifnographwiththisname,noedgecollectionornoedgewiththisidcouldbefound.412:Returnedifif-matchheaderisgiven,butthedocumentsrevisionisdifferent.

Examples

http://localhost:8529/_api/gharial/social/edge/relation/8310

HTTP/1.1202Accepted

showresponsebody

HTTPInterfaceforTraversals

Traversals

ArangoDB'sgraphtraversalsareexecutedontheserver.Traversalscanbeinitiatedbyclientsbysendingthetraversaldescriptionforexecutiontotheserver.

TraversalsinArangoDBareusedtowalkoveragraphstoredinoneedgecollection.Itcaneasilybedescribedwhichedgesofthegraphshouldbefollowedandwhichactionsshouldbeperformedoneachvisitedvertex.Furthermoretheorderingofvisitingthenodescanbespecified,forinstancedepth-firstorbreadth-firstsearchareoffered.

ExecutingTraversalsviaHTTP

executesatraversal

executeaserver-sidetraversal

POST/_api/traversal

Startsatraversalstartingfromagivenvertexandfollowing.edgescontainedinagivenedgeCollection.Therequestmustcontainthefollowingattributes.

sort:body(JavaScript)codeofacustomcomparisonfunctionfortheedges.Thesignatureofthisfunctionis(l,r)->integer(wherelandrareedges)andmustreturn-1iflissmallerthan,+1iflisgreaterthan,and0iflandrareequal.Thereasonforthisisthefollowing:Theorderofedgesreturnedforacertainvertexisundefined.Thisisbecausethereisnonaturalorderofedgesforavertexwithmultipleconnectededges.Toexplicitlydefinetheorderinwhichedgesonthevertexarefollowed,youcanspecifyanedgecomparatorfunctionwiththisattribute.NotethatthevalueherehastobeastringtoconformtotheJSONstandard,whichinturnisparsedasfunctionbodyontheserverside.Furthermorenotethatthisattributeisonlyusedforthestandardexpanders.Ifyouuseyourcustomexpanderyouhavetodothesortingyourselfwithintheexpandercode.direction:directionfortraversal

ifset,mustbeeither"outbound" ,"inbound" ,or"any"ifnotset,theexpanderattributemustbespecified

minDepth:ANDedwithanyexistingfilters):visitsonlynodesinatleastthegivendepthstartVertex:idofthestartVertex,e.g."users/foo" .visitor:body(JavaScript)codeofcustomvisitorfunctionfunctionsignature:(config,result,vertex,path,connected)->voidThevisitorfunctioncandoanything,butitsreturnvalueisignored.Topopulatearesult,usetheresultvariablebyreference.Notethattheconnectedargumentisonlypopulatedwhentheorderattributeissetto"preorder-expander" .itemOrder:itemiterationordercanbe"forward" or"backward"strategy:traversalstrategycanbe"depthfirst" or"breadthfirst"filter:defaultistoincludeallnodes:body(JavaScriptcode)ofcustomfilterfunctionfunctionsignature:(config,vertex,path)->mixedcanreturnfourdifferentstringvalues:

"exclude" ->thisvertexwillnotbevisited."prune" ->theedgesofthisvertexwillnotbefollowed."" orundefined->visitthevertexandfollowit'sedges.Array->containinganycombinationoftheabove.Ifthereisatleastone"exclude" or"prune" respectivlyiscontained,it'seffectwilloccur.

init:body(JavaScript)codeofcustomresultinitializationfunctionfunctionsignature:(config,result)->voidinitializeanyvaluesinresultwithwhatisrequiredmaxIterations:Maximumnumberofiterationsineachtraversal.Thisnumbercanbesettopreventendlessloopsintraversalofcyclicgraphs.WhenatraversalperformsasmanyiterationsasthemaxIterationsvalue,thetraversalwillabortwithanerror.IfmaxIterationsisnotset,aserver-definedvaluemaybeused.maxDepth:ANDedwithanyexistingfiltersvisitsonlynodesinatmostthegivendepthuniqueness:specifiesuniquenessforverticesandedgesvisited.Ifset,mustbeanobjectlikethis:"uniqueness":{"vertices":"none"|"global"|"path","edges":"none"|"global"|"path"}

Traversals

order:traversalordercanbe"preorder" ,"postorder" or"preorder-expander"graphName:nameofthegraphthatcontainstheedges.EitheredgeCollectionorgraphNamehastobegiven.IncasebothvaluesaresetthegraphNameisprefered.expander:body(JavaScript)codeofcustomexpanderfunctionmustbesetifdirectionattributeisnotsetfunctionsignature:(config,vertex,path)->arrayexpandermustreturnanarrayoftheconnectionsforvertexeachconnectionisanobjectwiththeattributesedgeandvertexedgeCollection:nameofthecollectionthatcontainstheedges.

IftheTraversalissuccessfullyexecutedHTTP200willbereturned.Additionallytheresultobjectwillbereturnedbythetraversal.

Forsuccessfultraversals,thereturnedJSONobjecthasthefollowingproperties:

error:booleanflagtoindicateifanerroroccurred(falseinthiscase)

code:theHTTPstatuscode

result:thereturnvalueofthetraversal

Ifthetraversalspecificationiseithermissingormalformed,theserverwillrespondwithHTTP400.

ThebodyoftheresponsewillthencontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:

error:booleanflagtoindicatethatanerroroccurred(trueinthiscase)

errorNum:theservererrornumber

errorMessage:adescriptiveerrormessage

Example:InthefollowingexamplestheunderlyinggraphwillcontainfivepersonsAlice,Bob,Charlie,DaveandEve.Wewillhavethefollowingdirectedrelations:

AliceknowsBobBobknowsCharlieBobknowsDaveEveknowsAliceEveknowsBob

ThestartingvertexwillalwaysbeAlice.

Followonlyoutboundedges

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/traversal<<EOF

"startVertex":"persons/alice",

"graphName":"knows_graph",

"direction":"outbound"

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_id":"persons/alice",

"_rev":"_WQ47gHO--B",

"name":"Alice"

Traversals

"_key":"bob",

"_id":"persons/bob",

"_rev":"_WQ47gHO--D",

"name":"Bob"

"_key":"charlie",

"_id":"persons/charlie",

"_rev":"_WQ47gHO--F",

"name":"Charlie"

"_key":"dave",

"_id":"persons/dave",

"_rev":"_WQ47gHS--_",

"name":"Dave"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"name":"Alice"

"edges":[

"_key":"14017",

"_id":"knows/14017",

"_from":"persons/alice",

"_to":"persons/bob",

"_rev":"_WQ47gHS--D",

"vertex":"alice"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"edges":[

"_key":"14017",

"_id":"knows/14017",

"vertex":"alice"

"_key":"14021",

"_id":"knows/14021",

"_from":"persons/bob",

"_to":"persons/charlie",

"_rev":"_WQ47gHS--F",

"vertex":"bob"

"vertices":[

Traversals

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"_rev":"_WQ47gHO--F",

"name":"Charlie"

"edges":[

"_key":"14017",

"_id":"knows/14017",

"vertex":"alice"

"_key":"14024",

"_id":"knows/14024",

"_to":"persons/dave",

"_rev":"_WQ47gHS--H",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"dave",

"_rev":"_WQ47gHS--_",

"name":"Dave"

"error":false,

"code":200

Example:Followonlyinboundedges

Traversals

"direction":"inbound"

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47g-K--_",

"name":"Alice"

"_key":"eve",

"_id":"persons/eve",

"_rev":"_WQ47g-K--H",

"name":"Eve"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"_rev":"_WQ47g-K--_",

"name":"Alice"

"edges":[

"_key":"13676",

"_id":"knows/13676",

"_from":"persons/eve",

"_to":"persons/alice",

"_rev":"_WQ47g-O--_",

"vertex":"eve"

"vertices":[

"_key":"alice",

"_rev":"_WQ47g-K--_",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47g-K--H",

"name":"Eve"

"error":false,

"code":200

Traversals

Example:Followanydirectionofedges

"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"global"

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47fuu--B",

"name":"Bob"

"_key":"charlie",

"_rev":"_WQ47fuu--D",

"name":"Charlie"

"_key":"dave",

"_rev":"_WQ47fuu--F",

"name":"Dave"

"_key":"eve",

"_rev":"_WQ47fuu--H",

"name":"Eve"

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

Traversals

"edges":[

"_key":"13099",

"_id":"knows/13099",

"_rev":"_WQ47fuy--_",

"vertex":"alice"

"vertices":[

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"edges":[

"_key":"13099",

"_id":"knows/13099",

"_rev":"_WQ47fuy--_",

"vertex":"alice"

"_key":"13103",

"_id":"knows/13103",

"_rev":"_WQ47fuy--B",

"vertex":"bob"

"vertices":[

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"_rev":"_WQ47fuu--D",

"name":"Charlie"

"edges":[

"_key":"13099",

"_id":"knows/13099",

"_rev":"_WQ47fuy--_",

"vertex":"alice"

Traversals

"_key":"13106",

"_id":"knows/13106",

"_rev":"_WQ47fuy--D",

"vertex":"bob"

"vertices":[

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"dave",

"_rev":"_WQ47fuu--F",

"name":"Dave"

"edges":[

"_key":"13099",

"_id":"knows/13099",

"_rev":"_WQ47fuy--_",

"vertex":"alice"

"_key":"13112",

"_id":"knows/13112",

"_rev":"_WQ47fuy--H",

"vertex":"eve"

"vertices":[

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"name":"Eve"

"edges":[

"_key":"13099",

"_id":"knows/13099",

Traversals

"_rev":"_WQ47fuy--_",

"vertex":"alice"

"_key":"13112",

"_id":"knows/13112",

"_rev":"_WQ47fuy--H",

"vertex":"eve"

"_key":"13109",

"_id":"knows/13109",

"_rev":"_WQ47fuy--F",

"vertex":"eve"

"vertices":[

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"name":"Eve"

"_key":"alice",

"_rev":"_WQ47fuu--_",

"name":"Alice"

"error":false,

"code":200

Example:ExcludingCharlieandBob

"direction":"outbound",

"filter":"if(vertex.name===\"Bob\"||vertex.name===\"Charlie\"){return\"exclude\";}return;"

HTTP/1.1200OK

Traversals

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47f5W--_",

"name":"Alice"

"_key":"dave",

"_rev":"_WQ47f5W--F",

"name":"Dave"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"_rev":"_WQ47f5W--_",

"name":"Alice"

"edges":[

"_key":"13505",

"_id":"knows/13505",

"_rev":"_WQ47f5W--J",

"vertex":"alice"

"_key":"13512",

"_id":"knows/13512",

"_rev":"_WQ47f5a--B",

"vertex":"bob"

"vertices":[

"_key":"alice",

"_rev":"_WQ47f5W--_",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f5W--B",

"name":"Bob"

"_key":"dave",

"_rev":"_WQ47f5W--F",

"name":"Dave"

"error":false,

"code":200

Traversals

Example:DonotfollowedgesfromBob

"filter":"if(vertex.name===\"Bob\"){return\"prune\";}return;"

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47f7m--B",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f7m--D",

"name":"Bob"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"_rev":"_WQ47f7m--B",

"name":"Alice"

"edges":[

"_key":"13588",

"_id":"knows/13588",

"_rev":"_WQ47f7q--_",

"vertex":"alice"

"vertices":[

"_key":"alice",

"_rev":"_WQ47f7m--B",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f7m--D",

"name":"Bob"

Traversals

"error":false,

"code":200

Example:Visitonlynodesinadepthofatleast2

"minDepth":2

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"charlie",

"_rev":"_WQ47gF---D",

"name":"Charlie"

"_key":"dave",

"_rev":"_WQ47gF---F",

"name":"Dave"

"paths":[

"edges":[

"_key":"13934",

"_id":"knows/13934",

"_rev":"_WQ47gF---J",

"vertex":"alice"

"_key":"13938",

"_id":"knows/13938",

"_rev":"_WQ47gF---L",

"vertex":"bob"

"vertices":[

"_key":"alice",

"_rev":"_WQ47gF---_",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47gF---B",

"name":"Bob"

Traversals

"_key":"charlie",

"_rev":"_WQ47gF---D",

"name":"Charlie"

"edges":[

"_key":"13934",

"_id":"knows/13934",

"_rev":"_WQ47gF---J",

"vertex":"alice"

"_key":"13941",

"_id":"knows/13941",

"_rev":"_WQ47gF---N",

"vertex":"bob"

"vertices":[

"_key":"alice",

"_rev":"_WQ47gF---_",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47gF---B",

"name":"Bob"

"_key":"dave",

"_rev":"_WQ47gF---F",

"name":"Dave"

"error":false,

"code":200

Example:Visitonlynodesinadepthofatmost1

"maxDepth":1

HTTP/1.1200OK

Traversals

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47gAa--_",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47gAa--B",

"name":"Bob"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"_rev":"_WQ47gAa--_",

"name":"Alice"

"edges":[

"_key":"13745",

"_id":"knows/13745",

"_rev":"_WQ47gAa--J",

"vertex":"alice"

"vertices":[

"_key":"alice",

"_rev":"_WQ47gAa--_",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47gAa--B",

"name":"Bob"

"error":false,

"code":200

Example:Usingavisitorfunctiontoreturnvertexidsonly

"visitor":"result.visited.vertices.push(vertex._id);"

Traversals

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"persons/alice",

"persons/bob",

"persons/charlie",

"persons/dave"

"paths":[]

"error":false,

"code":200

Example:Countallvisitednodesandreturnalistofnodesonly

"init":"result.visited=0;result.myVertices=[];",

"visitor":"result.visited++;result.myVertices.push(vertex);"

HTTP/1.1200OK

"result":{

"visited":4,

"myVertices":[

"_key":"alice",

"_rev":"_WQ47gMS--B",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47gMS--D",

"name":"Bob"

"_key":"charlie",

"_rev":"_WQ47gMS--F",

"name":"Charlie"

"_key":"dave",

"_rev":"_WQ47gMS--H",

"name":"Dave"

"error":false,

Traversals

"code":200

Example:ExpandonlyinboundedgesofAliceandoutboundedgesofEve

"expander":"varconnections=[];if(vertex.name===\"Alice\"){config.datasource.getInEdges(vertex).forEach(function(e)

{connections.push({vertex:require(\"internal\").db._document(e._from),edge:e});});}if(vertex.name===\"Eve\"){config.da

tasource.getOutEdges(vertex).forEach(function(e){connections.push({vertex:require(\"internal\").db._document(e._to),edge:e

});});}returnconnections;"

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47gOq--_",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47gOq--H",

"name":"Eve"

"_key":"bob",

"_rev":"_WQ47gOq--B",

"name":"Bob"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"_rev":"_WQ47gOq--_",

"name":"Alice"

"edges":[

"_key":"14302",

"_id":"knows/14302",

"_rev":"_WQ47gOq--P",

"vertex":"eve"

"vertices":[

"_key":"alice",

Traversals

"_rev":"_WQ47gOq--_",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"edges":[

"_key":"14302",

"_id":"knows/14302",

"_rev":"_WQ47gOq--P",

"vertex":"eve"

"_key":"14305",

"_id":"knows/14305",

"_rev":"_WQ47gOu--_",

"vertex":"eve"

"vertices":[

"_key":"alice",

"_rev":"_WQ47gOq--_",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"_key":"bob",

"_rev":"_WQ47gOq--B",

"name":"Bob"

"error":false,

"code":200

Example:Followthedepthfirststrategy

"direction":"any",

"strategy":"depthfirst"

HTTP/1.1200OK

Traversals

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47fyS--B",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47fyS--D",

"name":"Bob"

"_key":"charlie",

"_rev":"_WQ47fyS--F",

"name":"Charlie"

"_key":"dave",

"_rev":"_WQ47fyS--H",

"name":"Dave"

"_key":"eve",

"_rev":"_WQ47fyW--_",

"name":"Eve"

"_key":"alice",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47fyW--_",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"name":"Charlie"

"_key":"dave",

"name":"Dave"

"_key":"alice",

"name":"Alice"

"paths":[

Traversals

"edges":[],

"vertices":[

"_key":"alice",

"name":"Alice"

"edges":[

"_key":"13302",

"_id":"knows/13302",

"_rev":"_WQ47fyW--B",

"vertex":"alice"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"edges":[

"_key":"13302",

"_id":"knows/13302",

"vertex":"alice"

"_key":"13306",

"_id":"knows/13306",

"_rev":"_WQ47fyW--D",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"name":"Charlie"

Traversals

"edges":[

"_key":"13302",

"_id":"knows/13302",

"vertex":"alice"

"_key":"13309",

"_id":"knows/13309",

"_rev":"_WQ47fyW--F",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"dave",

"name":"Dave"

"edges":[

"_key":"13302",

"_id":"knows/13302",

"vertex":"alice"

"_key":"13315",

"_id":"knows/13315",

"_rev":"_WQ47fyW--J",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"_rev":"_WQ47fyW--_",

Traversals

"name":"Eve"

"edges":[

"_key":"13302",

"_id":"knows/13302",

"vertex":"alice"

"_key":"13315",

"_id":"knows/13315",

"vertex":"eve"

"_key":"13312",

"_id":"knows/13312",

"_rev":"_WQ47fyW--H",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"_rev":"_WQ47fyW--_",

"name":"Eve"

"_key":"alice",

"name":"Alice"

"edges":[

"_key":"13312",

"_id":"knows/13312",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

Traversals

"_key":"eve",

"_rev":"_WQ47fyW--_",

"name":"Eve"

"edges":[

"_key":"13312",

"_id":"knows/13312",

"vertex":"eve"

"_key":"13315",

"_id":"knows/13315",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47fyW--_",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"edges":[

"_key":"13312",

"_id":"knows/13312",

"vertex":"eve"

"_key":"13315",

"_id":"knows/13315",

"vertex":"eve"

"_key":"13306",

"_id":"knows/13306",

"_rev":"_WQ47fyW--D",

"vertex":"bob"

"vertices":[

Traversals

"_key":"alice",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47fyW--_",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"name":"Charlie"

"edges":[

"_key":"13312",

"_id":"knows/13312",

"vertex":"eve"

"_key":"13315",

"_id":"knows/13315",

"vertex":"eve"

"_key":"13309",

"_id":"knows/13309",

"_rev":"_WQ47fyW--F",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47fyW--_",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"dave",

Traversals

"name":"Dave"

"edges":[

"_key":"13312",

"_id":"knows/13312",

"vertex":"eve"

"_key":"13315",

"_id":"knows/13315",

"vertex":"eve"

"_key":"13302",

"_id":"knows/13302",

"vertex":"alice"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47fyW--_",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"alice",

"name":"Alice"

"error":false,

"code":200

Example:Usingpostorderordering

Traversals

"direction":"any",

"order":"postorder"

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"charlie",

"_rev":"_WQ47gJa--F",

"name":"Charlie"

"_key":"dave",

"_rev":"_WQ47gJa--H",

"name":"Dave"

"_key":"alice",

"_rev":"_WQ47gJa--B",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47gJa--J",

"name":"Eve"

"_key":"bob",

"_rev":"_WQ47gJa--D",

"name":"Bob"

"_key":"charlie",

"name":"Charlie"

"_key":"dave",

"name":"Dave"

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"name":"Eve"

"_key":"alice",

Traversals

"name":"Alice"

"paths":[

"edges":[

"_key":"14100",

"_id":"knows/14100",

"_rev":"_WQ47gJa--L",

"vertex":"alice"

"_key":"14104",

"_id":"knows/14104",

"_rev":"_WQ47gJa--N",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"name":"Charlie"

"edges":[

"_key":"14100",

"_id":"knows/14100",

"vertex":"alice"

"_key":"14107",

"_id":"knows/14107",

"_rev":"_WQ47gJe--_",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

Traversals

"name":"Bob"

"_key":"dave",

"name":"Dave"

"edges":[

"_key":"14100",

"_id":"knows/14100",

"vertex":"alice"

"_key":"14113",

"_id":"knows/14113",

"_rev":"_WQ47gJe--D",

"vertex":"eve"

"_key":"14110",

"_id":"knows/14110",

"_rev":"_WQ47gJe--B",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"name":"Eve"

"_key":"alice",

"name":"Alice"

"edges":[

"_key":"14100",

"_id":"knows/14100",

"vertex":"alice"

"_key":"14113",

Traversals

"_id":"knows/14113",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"name":"Eve"

"edges":[

"_key":"14100",

"_id":"knows/14100",

"vertex":"alice"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"edges":[

"_key":"14110",

"_id":"knows/14110",

"vertex":"eve"

"_key":"14113",

"_id":"knows/14113",

"vertex":"eve"

"_key":"14104",

"_id":"knows/14104",

Traversals

"_rev":"_WQ47gJa--N",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"name":"Charlie"

"edges":[

"_key":"14110",

"_id":"knows/14110",

"vertex":"eve"

"_key":"14113",

"_id":"knows/14113",

"vertex":"eve"

"_key":"14107",

"_id":"knows/14107",

"_rev":"_WQ47gJe--_",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"_key":"bob",

Traversals

"name":"Bob"

"_key":"dave",

"name":"Dave"

"edges":[

"_key":"14110",

"_id":"knows/14110",

"vertex":"eve"

"_key":"14113",

"_id":"knows/14113",

"vertex":"eve"

"_key":"14100",

"_id":"knows/14100",

"vertex":"alice"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"alice",

"name":"Alice"

"edges":[

"_key":"14110",

"_id":"knows/14110",

"vertex":"eve"

"_key":"14113",

Traversals

"_id":"knows/14113",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"edges":[

"_key":"14110",

"_id":"knows/14110",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"edges":[],

"vertices":[

"_key":"alice",

"name":"Alice"

"error":false,

"code":200

Example:

Traversals

Usingbackwarditem-ordering:

"direction":"any",

"itemOrder":"backward"

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47fwe--B",

"name":"Alice"

"_key":"eve",

"_rev":"_WQ47fwi--B",

"name":"Eve"

"_key":"bob",

"_rev":"_WQ47fwe--D",

"name":"Bob"

"_key":"alice",

"name":"Alice"

"_key":"dave",

"_rev":"_WQ47fwi--_",

"name":"Dave"

"_key":"charlie",

"_rev":"_WQ47fwe--F",

"name":"Charlie"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"name":"Eve"

"_key":"alice",

"name":"Alice"

"_key":"dave",

Traversals

"_rev":"_WQ47fwi--_",

"name":"Dave"

"_key":"charlie",

"name":"Charlie"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"name":"Alice"

"edges":[

"_key":"13203",

"_id":"knows/13203",

"_rev":"_WQ47fwi--J",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"edges":[

"_key":"13203",

"_id":"knows/13203",

"vertex":"eve"

"_key":"13206",

"_id":"knows/13206",

"_rev":"_WQ47fwi--L",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

Traversals

"_key":"eve",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"edges":[

"_key":"13203",

"_id":"knows/13203",

"vertex":"eve"

"_key":"13206",

"_id":"knows/13206",

"vertex":"eve"

"_key":"13193",

"_id":"knows/13193",

"_rev":"_WQ47fwi--D",

"vertex":"alice"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"alice",

"name":"Alice"

"edges":[

"_key":"13203",

"_id":"knows/13203",

"vertex":"eve"

Traversals

"_key":"13206",

"_id":"knows/13206",

"vertex":"eve"

"_key":"13200",

"_id":"knows/13200",

"_rev":"_WQ47fwi--H",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"eve",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"dave",

"_rev":"_WQ47fwi--_",

"name":"Dave"

"edges":[

"_key":"13203",

"_id":"knows/13203",

"vertex":"eve"

"_key":"13206",

"_id":"knows/13206",

"vertex":"eve"

"_key":"13197",

"_id":"knows/13197",

"_rev":"_WQ47fwi--F",

"vertex":"bob"

"vertices":[

"_key":"alice",

Traversals

"name":"Alice"

"_key":"eve",

"name":"Eve"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"name":"Charlie"

"edges":[

"_key":"13193",

"_id":"knows/13193",

"vertex":"alice"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"edges":[

"_key":"13193",

"_id":"knows/13193",

"vertex":"alice"

"_key":"13206",

"_id":"knows/13206",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

Traversals

"_key":"bob",

"name":"Bob"

"_key":"eve",

"name":"Eve"

"edges":[

"_key":"13193",

"_id":"knows/13193",

"vertex":"alice"

"_key":"13206",

"_id":"knows/13206",

"vertex":"eve"

"_key":"13203",

"_id":"knows/13203",

"vertex":"eve"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"eve",

"name":"Eve"

"_key":"alice",

"name":"Alice"

"edges":[

"_key":"13193",

"_id":"knows/13193",

"vertex":"alice"

Traversals

"_key":"13200",

"_id":"knows/13200",

"_rev":"_WQ47fwi--H",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"dave",

"_rev":"_WQ47fwi--_",

"name":"Dave"

"edges":[

"_key":"13193",

"_id":"knows/13193",

"vertex":"alice"

"_key":"13197",

"_id":"knows/13197",

"_rev":"_WQ47fwi--F",

"vertex":"bob"

"vertices":[

"_key":"alice",

"name":"Alice"

"_key":"bob",

"name":"Bob"

"_key":"charlie",

"name":"Charlie"

"error":false,

"code":200

Traversals

Example:Edgesshouldonlybeincludedonceglobally,butnodesareincludedeverytimetheyarevisited

"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"global"

HTTP/1.1200OK

"result":{

"visited":{

"vertices":[

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f2q--C",

"name":"Bob"

"_key":"charlie",

"_rev":"_WQ47f2q--E",

"name":"Charlie"

"_key":"dave",

"_rev":"_WQ47f2q--G",

"name":"Dave"

"_key":"eve",

"_rev":"_WQ47f2q--I",

"name":"Eve"

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

"paths":[

"edges":[],

"vertices":[

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

Traversals

"edges":[

"_key":"13411",

"_id":"knows/13411",

"_rev":"_WQ47f2q--K",

"vertex":"alice"

"vertices":[

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f2q--C",

"name":"Bob"

"edges":[

"_key":"13411",

"_id":"knows/13411",

"_rev":"_WQ47f2q--K",

"vertex":"alice"

"_key":"13415",

"_id":"knows/13415",

"_rev":"_WQ47f2u--_",

"vertex":"bob"

"vertices":[

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f2q--C",

"name":"Bob"

"_key":"charlie",

"_rev":"_WQ47f2q--E",

"name":"Charlie"

"edges":[

"_key":"13411",

"_id":"knows/13411",

Traversals

"_rev":"_WQ47f2q--K",

"vertex":"alice"

"_key":"13418",

"_id":"knows/13418",

"_rev":"_WQ47f2u--B",

"vertex":"bob"

"vertices":[

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f2q--C",

"name":"Bob"

"_key":"dave",

"_rev":"_WQ47f2q--G",

"name":"Dave"

"edges":[

"_key":"13411",

"_id":"knows/13411",

"_rev":"_WQ47f2q--K",

"vertex":"alice"

"_key":"13424",

"_id":"knows/13424",

"_rev":"_WQ47f2u--F",

"vertex":"eve"

"vertices":[

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f2q--C",

"name":"Bob"

"_key":"eve",

"_rev":"_WQ47f2q--I",

"name":"Eve"

"edges":[

Traversals

"_key":"13411",

"_id":"knows/13411",

"_rev":"_WQ47f2q--K",

"vertex":"alice"

"_key":"13424",

"_id":"knows/13424",

"_rev":"_WQ47f2u--F",

"vertex":"eve"

"_key":"13421",

"_id":"knows/13421",

"_rev":"_WQ47f2u--D",

"vertex":"eve"

"vertices":[

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

"_key":"bob",

"_rev":"_WQ47f2q--C",

"name":"Bob"

"_key":"eve",

"_rev":"_WQ47f2q--I",

"name":"Eve"

"_key":"alice",

"_rev":"_WQ47f2q--A",

"name":"Alice"

"error":false,

"code":200

Example:Iftheunderlyinggraphiscyclic,maxIterationsshouldbeset

TheunderlyinggraphhastwoverticesAliceandBob.Withthedirectededges:

AliceknowsBobBobknowsAlice

"direction":"any",

Traversals

"uniqueness":{

"vertices":"none",

"edges":"none"

"maxIterations":5

HTTP/1.1500InternalServerError

"error":true,

"code":500,

"errorNum":1909,

"errorMessage":"toomanyiterations-tryincreasingthevalueof'maxIterations'"

ReturnCodes

200:IfthetraversalisfullyexecutedHTTP200willbereturned.400:Ifthetraversalspecificationiseithermissingormalformed,theserverwillrespondwithHTTP400.404:TheserverwillrespondedwithHTTP404ifthespecifiededgecollectiondoesnotexist,orthespecifiedstartvertexcannotbefound.500:TheserverwillrespondedwithHTTP500whenanerroroccursinsidethetraversalorifatraversalperformsmorethanmaxIterationsiterations.

Examples

InthefollowingexamplestheunderlyinggraphwillcontainfivepersonsAlice,Bob,Charlie,DaveandEve.Wewillhavethefollowingdirectedrelations:

AliceknowsBobBobknowsCharlieBobknowsDaveEveknowsAliceEveknowsBobThestartingvertexwillalwaysbeAlice.Followonlyoutboundedges

"direction":"outbound"

HTTP/1.1200OK

showresponsebodyFollowonlyinboundedges

"direction":"inbound"

Traversals

HTTP/1.1200OK

showresponsebodyFollowanydirectionofedges

"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"global"

HTTP/1.1200OK

showresponsebodyExcludingCharlieandBob

"filter":"if(vertex.name===\"Bob\"||vertex.name===\"Charlie\"){return

\"exclude\";}return;"

HTTP/1.1200OK

showresponsebodyDonotfollowedgesfromBob

"filter":"if(vertex.name===\"Bob\"){return\"prune\";}return;"

Traversals

HTTP/1.1200OK

showresponsebodyVisitonlynodesinadepthofatleast2

"minDepth":2

HTTP/1.1200OK

showresponsebodyVisitonlynodesinadepthofatmost1

"maxDepth":1

HTTP/1.1200OK

showresponsebodyUsingavisitorfunctiontoreturnvertexidsonly

"visitor":"result.visited.vertices.push(vertex._id);"

HTTP/1.1200OK

Traversals

showresponsebodyCountallvisitednodesandreturnalistofnodesonly

"init":"result.visited=0;result.myVertices=[];",

"visitor":"result.visited++;result.myVertices.push(vertex);"

HTTP/1.1200OK

showresponsebodyExpandonlyinboundedgesofAliceandoutboundedgesofEve

"expander":"varconnections=[];if(vertex.name===\"Alice\")

{config.datasource.getInEdges(vertex).forEach(function(e){connections.push({vertex:

require(\"internal\").db._document(e._from),edge:e});});}if(vertex.name===\"Eve\")

{config.datasource.getOutEdges(vertex).forEach(function(e){connections.push({vertex:

require(\"internal\").db._document(e._to),edge:e});});}returnconnections;"

HTTP/1.1200OK

showresponsebodyFollowthedepthfirststrategy

"direction":"any",

"strategy":"depthfirst"

HTTP/1.1200OK

Traversals

showresponsebodyUsingpostorderordering

"direction":"any",

"order":"postorder"

HTTP/1.1200OK

showresponsebodyUsingbackwarditem-ordering:

"direction":"any",

"itemOrder":"backward"

HTTP/1.1200OK

showresponsebodyEdgesshouldonlybeincludedonceglobally,butnodesareincludedeverytimetheyarevisited

"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"global"

HTTP/1.1200OK

Traversals

showresponsebodyIftheunderlyinggraphiscyclic,maxIterationsshouldbesetTheunderlyinggraphhastwoverticesAliceandBob.Withthedirectededges:

AliceknowsBobBobknowsAlice

"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"none"

"maxIterations":5

showresponsebodyAllexampleswereusingthisgraph:

Traversals

HTTPInterfaceforAQLQueryCursors

DatabaseCursors

ThisisanintroductiontoArangoDB'sHTTPInterfaceforQueries.ResultsofAQLandsimplequeriesarereturnedascursorsinordertobatchthecommunicationbetweenserverandclient.Eachcallreturnsanumberofdocumentsinabatchandanindicationifthecurrentbatchhasbeenthefinalbatch.Dependingonthequery,thetotalnumberofdocumentsintheresultsetmightormightnotbeknowninadvance.Inordertofreeserverresourcestheclientshoulddeletethecursorassoonasitisnolongerneeded.

Toexecuteaquery,thequerydetailsneedtobeshippedfromtheclienttotheserverviaanHTTPPOSTrequest.

AQLQueryCursors

RetrievingqueryresultsSelectqueriesareexecutedon-the-flyontheserverandtheresultsetwillbereturnedbacktotheclient.

Therearetwowaystheclientcangettheresultsetfromtheserver:

InasingleroundtripUsingacursor

Singleroundtrip

Theserverwillonlytransferacertainnumberofresultdocumentsbacktotheclientinoneroundtrip.ThisnumberiscontrollablebytheclientbysettingthebatchSizeattributewhenissuingthequery.

Ifthecompleteresultcanbetransferredtotheclientinonego,theclientdoesnotneedtoissueanyfurtherrequest.TheclientcancheckwhetherithasretrievedthecompleteresultsetbycheckingthehasMoreattributeoftheresultset.Ifitissettofalse,thentheclienthasfetchedthecompleteresultsetfromtheserver.Inthiscasenoserversidecursorwillbecreated.

>curl--data@--XPOST--dump-http://localhost:8529/_api/cursor

{"query":"FORuINusersLIMIT2RETURNu","count":true,"batchSize":2}

HTTP/1.1201Created

Content-type:application/json

"hasMore":false,

"error":false,

"result":[

"name":"user1",

"_rev":"210304551",

"_key":"210304551",

"_id":"users/210304551"

"name":"user2",

"_rev":"210304552",

"_key":"210304552",

"_id":"users/210304552"

"code":201,

"count":2

Usingacursor

Iftheresultsetcontainsmoredocumentsthanshouldbetransferredinasingleroundtrip(i.e.assetviathebatchSizeattribute),theserverwillreturnthefirstfewdocumentsandcreateatemporarycursor.Thecursoridentifierwillalsobereturnedtotheclient.Theserverwillputthecursoridentifierintheidattributeoftheresponseobject.Furthermore,thehasMoreattributeoftheresponseobjectwillbesettotrue.Thisisanindicationfortheclientthatthereareadditionalresultstofetchfromtheserver.

Examples:

Createandextractfirstbatch:

{"query":"FORuINusersLIMIT5RETURNu","count":true,"batchSize":2}

HTTP/1.1201Created

"hasMore":true,

"error":false,

"id":"26011191",

QueryResults

"result":[

"name":"user1",

"_rev":"258801191",

"_key":"258801191",

"_id":"users/258801191"

"name":"user2",

"_rev":"258801192",

"_key":"258801192",

"_id":"users/258801192"

"code":201,

"count":5

Extractnextbatch,stillhavemore:

>curl-XPUT--dump-http://localhost:8529/_api/cursor/26011191

HTTP/1.1200OK

"hasMore":true,

"error":false,

"id":"26011191",

"result":[

"name":"user3",

"_rev":"258801193",

"_key":"258801193",

"_id":"users/258801193"

"name":"user4",

"_rev":"258801194",

"_key":"258801194",

"_id":"users/258801194"

"code":200,

"count":5

Extractnextbatch,done:

HTTP/1.1200OK

"hasMore":false,

"error":false,

"result":[

"name":"user5",

"_rev":"258801195",

"_key":"258801195",

"_id":"users/258801195"

"code":200,

"count":5

DonotdothisbecausehasMorenowhasavalueoffalse:

QueryResults

HTTP/1.1404NotFound

"errorNum":1600,

"errorMessage":"cursornotfound:disposedorunknowncursor",

"error":true,

"code":404

Modifyingdocuments

The_api/cursorendpointcanalsobeusedtoexecutemodifyingqueries.

ThefollowingexampleappendsavalueintothearrayarrayValueofthedocumentwithkeytestinthecollectiondocuments.Normalupdatebehavioristoreplacetheattributecompletely,andusinganupdateAQLquerywiththePUSH()functionallowstoappendtothearray.

curl--data@--XPOST--dumphttp://127.0.0.1:8529/_api/cursor

{"query":"FORdocINdocumentsFILTERdoc._key==@myKeyUPDATEdoc._keyWITH{arrayValue:PUSH(doc.arrayValue,@value)}IN

documents","bindVars":{"myKey":"test","value":42}}

HTTP/1.1201Created

Content-type:application/json;charset=utf-8

"result":[],

"hasMore":false,

"extra":{

"stats":{

"writesExecuted":1,

"writesIgnored":0,

"scannedFull":0,

"scannedIndex":1,

"filtered":0

"warnings":[]

"error":false,

"code":201

Settingamemorylimit

Tosetamemorylimitforthequery,thememoryLimitoptioncanbepassedtotheserver.Thememorylimitspecifiesthemaximumnumberofbytesthatthequeryisallowedtouse.WhenasingleAQLqueryreachesthespecifiedlimitvalue,thequerywillbeabortedwitharesourcelimitexceededexception.Inacluster,thememoryaccountingisdonepershard,sothelimitvalueiseffectivelyamemorylimitperquerypershard.

{"query":"FORiIN1..100000SORTiRETURNi","memoryLimit":100000}

Server:ArangoDB

Connection:Keep-Alive

Content-Type:application/json;charset=utf-8

Content-Length:115

{"error":true,"errorMessage":"querywouldusemorememorythanallowed(whileexecuting)","code":500,"errorNum":32}

Ifnomemorylimitisspecified,thentheserverdefaultvalue(controlledbystartupoption--query.memory-limitwillbeusedforrestrictingthemaximumamountofmemorythequerycanuse.Amemorylimitvalueof0meansthatthemaximumamountofmemoryforthequeryisnotrestricted.

QueryResults

AccessingCursorsviaHTTP

Createcursor

createacursorandreturnthefirstresults

POST/_api/cursorAJSONobjectdescribingthequeryandqueryparameters.

count:indicateswhetherthenumberofdocumentsintheresultsetshouldbereturnedinthe"count"attributeoftheresult.Calculatingthe"count"attributemighthaveaperformanceimpactforsomequeriesinthefuturesothisoptionisturnedoffbydefault,and"count"isonlyreturnedwhenrequested.batchSize:maximumnumberofresultdocumentstobetransferredfromtheservertotheclientinoneroundtrip.Ifthisattributeisnotset,aserver-controlleddefaultvaluewillbeused.AbatchSizevalueof0isdisallowed.cache:flagtodeterminewhethertheAQLquerycacheshallbeused.Ifsettofalse,thenanyquerycachelookupwillbeskippedforthequery.Ifsettotrue,itwillleadtothequerycachebeingcheckedforthequeryifthequerycachemodeiseitheronordemand.memoryLimit:themaximumnumberofmemory(measuredinbytes)thatthequeryisallowedtouse.Ifset,thenthequerywillfailwitherror"resourcelimitexceeded"incaseitallocatestoomuchmemory.Avalueof0indicatesthatthereisnomemorylimit.ttl:Thetime-to-liveforthecursor(inseconds).Thecursorwillberemovedontheserverautomaticallyafterthespecifiedamountoftime.Thisisusefultoensuregarbagecollectionofcursorsthatarenotfullyfetchedbyclients.Ifnotset,aserver-definedvaluewillbeused.query:containsthequerystringtobeexecutedbindVars(object):key/valuepairsrepresentingthebindparameters.options:

failOnWarning:Whensettotrue,thequerywillthrowanexceptionandabortinsteadofproducingawarning.Thisoptionshouldbeusedduringdevelopmenttocatchpotentialissuesearly.Whentheattributeissettofalse,warningswillnotbepropagatedtoexceptionsandwillbereturnedwiththequeryresult.Thereisalsoaserverconfigurationoption--query.fail-on-warningforsettingthedefaultvalueforfailOnWarningsoitdoesnotneedtobesetonaper-querylevel.profile:Ifsettotrue,thentheadditionalqueryprofilinginformationwillbereturnedinthesub-attributeprofileoftheextrareturnattributeifthequeryresultisnotservedfromthequerycache.maxTransactionSize:Transactionsizelimitinbytes.HonoredbytheRocksDBstorageengineonly.skipInaccessibleCollections:AQLqueries(especiallygraphtraversals)willtreatcollectiontowhichauserhasnoaccessrightsasifthesecollectionswereempty.Insteadofreturningaforbiddenaccesserror,yourquerieswillexecutenormally.Thisisintendedtohelpwithcertainuse-cases:AgraphcontainsseveralcollectionsanddifferentusersexecuteAQLqueriesonthatgraph.Youcannownaturallylimittheaccessibleresultsbychangingtheaccessrightsofusersoncollections.ThisfeatureisonlyavailableintheEnterpriseEdition.maxWarningCount:Limitsthemaximumnumberofwarningsaquerywillreturn.Thenumberofwarningsaquerywillreturnislimitedto10bydefault,butthatnumbercanbeincreasedordecreasedbysettingthisattribute.intermediateCommitCount:Maximumnumberofoperationsafterwhichanintermediatecommitisperformedautomatically.HonoredbytheRocksDBstorageengineonly.satelliteSyncWait:ThisenterpriseparameterallowstoconfigurehowlongaDBServerwillhavetimetobringthesatellitecollectionsinvolvedinthequeryintosync.Thedefaultvalueis60.0(seconds).Whenthemaxtimehasbeenreachedthequerywillbestopped.fullCount:ifsettotrueandthequerycontainsaLIMITclause,thentheresultwillhaveanextraattributewiththesub-attributesstatsandfullCount,{...,"extra":{"stats":{"fullCount":123}}}.ThefullCountattributewillcontainthenumberofdocumentsintheresultbeforethelastLIMITinthequerywasapplied.Itcanbeusedtocountthenumberofdocumentsthatmatchcertainfiltercriteria,butonlyreturnasubsetofthem,inonego.ItisthussimilartoMySQL'sSQL_CALC_FOUND_ROWShint.NotethatsettingtheoptionwilldisableafewLIMIToptimizationsandmayleadtomoredocumentsbeingprocessed,andthusmakequeriesrunlonger.NotethatthefullCountattributewillonlybepresentintheresultifthequeryhasaLIMITclauseandtheLIMITclauseisactuallyusedinthequery.intermediateCommitSize:Maximumtotalsizeofoperationsafterwhichanintermediatecommitisperformedautomatically.HonoredbytheRocksDBstorageengineonly.optimizer.rules(string):Alistofto-be-includedorto-be-excludedoptimizerrulescanbeputintothisattribute,tellingtheoptimizertoincludeorexcludespecificrules.Todisablearule,prefixitsnamewitha-,toenablearule,prefixitwitha+.Thereisalsoapseudo-ruleall,whichwillmatchalloptimizerrules.

AccessingCursors

maxPlans:LimitsthemaximumnumberofplansthatarecreatedbytheAQLqueryoptimizer.

Thequerydetailsincludethequerystringplusoptionalqueryoptionsandbindparameters.ThesevaluesneedtobepassedinaJSONrepresentationinthebodyofthePOSTrequest.

HTTP201isreturnediftheresultsetcanbecreatedbytheserver.

count:thetotalnumberofresultdocumentsavailable(onlyavailableifthequerywasexecutedwiththecountattributeset)code:theHTTPstatuscodeextra:anoptionalJSONobjectwithextrainformationaboutthequeryresultcontainedinitsstatssub-attribute.Fordata-modificationqueries,theextra.statssub-attributewillcontainthenumberofmodifieddocumentsandthenumberofdocumentsthatcouldnotbemodifiedduetoanerror(ifignoreErrorsqueryoptionisspecified)cached:abooleanflagindicatingwhetherthequeryresultwasservedfromthequerycacheornot.Ifthequeryresultisservedfromthequerycache,theextrareturnattributewillnotcontainanystatssub-attributeandnoprofilesub-attribute.hasMore:Abooleanindicatorwhethertherearemoreresultsavailableforthecursorontheserverresult(anonymousjsonobject):anarrayofresultdocuments(mightbeemptyifqueryhasnoresults)error:Aflagtoindicatethatanerroroccurred(falseinthiscase)id:idoftemporarycursorcreatedontheserver(optional,seeabove)

HTTP400isreturnediftheJSONrepresentationismalformedorthequeryspecificationismissingfromtherequest.IftheJSONrepresentationismalformedorthequeryspecificationismissingfromtherequest,theserverwillrespondwithHTTP400.ThebodyoftheresponsewillcontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:

errorMessage:adescriptiveerrormessageIfthequeryspecificationiscomplete,theserverwillprocessthequery.Ifanerroroccursduringqueryprocessing,theserverwillrespondwithHTTP400.Again,thebodyoftheresponsewillcontaindetailsabouttheerror.Alistofqueryerrorscanbefoundhere.errorNum:theservererrornumbercode:theHTTPstatuscodeerror:booleanflagtoindicatethatanerroroccurred(trueinthiscase)

Example:Executeaqueryandextracttheresultinasinglego

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF

"query":"FORpINproductsLIMIT2RETURNp",

"count":true,

"batchSize":2

HTTP/1.1201Created

"result":[

"_key":"10541",

"_rev":"_WQ47Xre--B",

"hello2":"world1"

AccessingCursors

"_key":"10537",

"_rev":"_WQ47Xre--_",

"hello1":"world1"

"hasMore":false,

"count":2,

"cached":false,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":2,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.00009870529174804688

"warnings":[]

"error":false,

"code":201

Example:Executeaqueryandextractapartoftheresult

"count":true,

"batchSize":2

HTTP/1.1201Created

"error":false,

"code":201,

"result":[

"_key":"10525",

"_rev":"_WQ47Xqa--F",

"hello5":"world1"

"_key":"10512",

"_rev":"_WQ47XqW--_",

"hello1":"world1"

"hasMore":true,

"id":"10528",

"count":5,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":5,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.00009226799011230469

AccessingCursors

"warnings":[]

"cached":false

Example:Usingthequeryoption"fullCount"

"query":"FORiIN1..1000FILTERi>500LIMIT10RETURNi",

"count":true,

"options":{

"fullCount":true

HTTP/1.1201Created

"result":[

"hasMore":false,

"count":10,

"cached":false,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":0,

"scannedIndex":0,

"filtered":500,

"httpRequests":0,

"fullCount":500,

"executionTime":0.00023555755615234375

"warnings":[]

"error":false,

"code":201

Example:Enablinganddisablingoptimizerrules

"query":"FORiIN1..10LETa=1LETb=2FILTERa+b==3RETURNi",

"count":true,

"options":{

"maxPlans":1,

"optimizer":{

AccessingCursors

"rules":[

"-all",

"+remove-unnecessary-filters"

HTTP/1.1201Created

"result":[

"hasMore":false,

"count":10,

"cached":false,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":0,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.00011301040649414062

"warnings":[]

"error":false,

"code":201

Example:Executeadata-modificationqueryandretrievethenumberofmodifieddocuments

"query":"FORpINproductsREMOVEpINproducts"

HTTP/1.1201Created

"result":[],

"hasMore":false,

"cached":false,

"extra":{

"stats":{

"writesExecuted":2,

"writesIgnored":0,

"scannedFull":2,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.0001289844512939453

AccessingCursors

"warnings":[]

"error":false,

"code":201

Example:Executeadata-modificationquerywithoptionignoreErrors

"query":"REMOVE'bar'INproductsOPTIONS{ignoreErrors:true}"

HTTP/1.1201Created

"result":[],

"hasMore":false,

"cached":false,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":1,

"scannedFull":0,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.00011205673217773438

"warnings":[]

"error":false,

"code":201

Example:Badquery-Missingbody

shell>curl-XPOST--dump-http://localhost:8529/_api/cursor

"error":true,

"errorMessage":"queryisempty",

"code":400,

"errorNum":1502

Example:Badquery-Unknowncollection

AccessingCursors

"query":"FORuINunknowncollLIMIT2RETURNu",

"count":true,

"batchSize":2

HTTP/1.1404NotFound

"error":true,

"errorMessage":"AQL:collectionnotfound:unknowncoll(whileparsing)",

"code":404,

"errorNum":1203

Example:Badquery-Executeadata-modificationquerythatattemptstoremoveanon-existingdocument

"query":"REMOVE'foo'INproducts"

HTTP/1.1404NotFound

"error":true,

"errorMessage":"AQL:documentnotfound(whileexecuting)",

"code":404,

"errorNum":1202

"count":true,

"batchSize":2

HTTP/1.1201Created

showresponsebodyExecuteaqueryandextractapartoftheresult

"count":true,

"batchSize":2

AccessingCursors

HTTP/1.1201Created

showresponsebodyUsingthequeryoption"fullCount"

"query":"FORiIN1..1000FILTERi>500LIMIT10RETURNi",

"count":true,

"options":{

"fullCount":true

HTTP/1.1201Created

showresponsebodyEnablinganddisablingoptimizerrules

"query":"FORiIN1..10LETa=1LETb=2FILTERa+b==3RETURNi",

"count":true,

"options":{

"maxPlans":1,

"optimizer":{

"rules":[

"-all",

"+remove-unnecessary-filters"

HTTP/1.1201Created

showresponsebodyExecuteadata-modificationqueryandretrievethenumberofmodifieddocuments

"query":"FORpINproductsREMOVEpINproducts"

AccessingCursors

HTTP/1.1201Created

showresponsebodyExecuteadata-modificationquerywithoptionignoreErrors

"query":"REMOVE'bar'INproductsOPTIONS{ignoreErrors:true}"

HTTP/1.1201Created

showresponsebodyBadquery-Missingbody

shell>curl-XPOST--dump-http://localhost:8529/_api/cursor

showresponsebodyBadquery-Unknowncollection

"query":"FORuINunknowncollLIMIT2RETURNu",

"count":true,

"batchSize":2

HTTP/1.1404NotFound

showresponsebodyBadquery-Executeadata-modificationquerythatattemptstoremoveanon-existingdocument

"query":"REMOVE'foo'INproducts"

AccessingCursors

HTTP/1.1404NotFound

showresponsebody

Readnextbatchfromcursor

returnthenextresultsfromanexistingcursor

PUT/_api/cursor/{cursor-identifier}

PathParameters

cursor-identifier(required):Thenameofthecursor

Ifthecursorisstillalive,returnsanobjectwiththefollowingattributes:

id:thecursor-identifierresult:alistofdocumentsforthecurrentbatchhasMore:falseifthiswasthelastbatchcount:ifpresentthetotalnumberofelements

NotethatevenifhasMorereturnstrue,thenextcallmightstillreturnnodocuments.If,however,hasMoreisfalse,thenthecursorisexhausted.OncethehasMoreattributehasavalueoffalse,theclientcanstop.

Example:Validrequestfornextbatch

"count":true,

"batchSize":2

shell>curl-XPUT--dump-http://localhost:8529/_api/cursor/10636

HTTP/1.1200OK

"error":false,

"code":200,

"result":[

"_key":"10627",

"_rev":"_WQ47XwS--D",

"hello3":"world1"

"_key":"10624",

"_rev":"_WQ47XwS--B",

"hello2":"world1"

"hasMore":true,

"id":"10636",

"count":5,

"extra":{

"stats":{

"writesExecuted":0,

AccessingCursors

"writesIgnored":0,

"scannedFull":5,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.000133514404296875

"warnings":[]

"cached":false

Example:Missingidentifier

shell>curl-XPUT--dump-http://localhost:8529/_api/cursor

"error":true,

"errorMessage":"expectingPUT/_api/cursor/<cursor-id>",

"code":400,

"errorNum":400

Example:Unknownidentifier

HTTP/1.1404NotFound

"error":true,

"errorMessage":"cursornotfound",

"code":404,

"errorNum":1600

ReturnCodes

200:TheserverwillrespondwithHTTP200incaseofsuccess.400:Ifthecursoridentifierisomitted,theserverwillrespondwithHTTP404.404:Ifnocursorwiththespecifiedidentifiercanbefound,theserverwillrespondwithHTTP404.

Examples

Validrequestfornextbatch

"count":true,

"batchSize":2

AccessingCursors

HTTP/1.1200OK

showresponsebodyMissingidentifier

shell>curl-XPUT--dump-http://localhost:8529/_api/cursor

showresponsebodyUnknownidentifier

HTTP/1.1404NotFound

showresponsebody

Deletecursor

disposeanexistingcursor

DELETE/_api/cursor/{cursor-identifier}

PathParameters

cursor-identifier(required):Theidofthecursor

Deletesthecursorandfreestheresourcesassociatedwithit.

Thecursorwillautomaticallybedestroyedontheserverwhentheclienthasretrievedalldocumentsfromit.TheclientcanalsoexplicitlydestroythecursoratanyearliertimeusinganHTTPDELETErequest.ThecursoridmustbeincludedaspartoftheURL.

Note:theserverwillalsodestroyabandonedcursorsautomaticallyafteracertainserver-controlledtimeouttoavoidresourceleakage.

Example:

"count":true,

"batchSize":2

HTTP/1.1201Created

AccessingCursors

"error":false,

"code":201,

"result":[

"_key":"10557",

"_rev":"_WQ47Xsm--B",

"hello2":"world1"

"_key":"10566",

"_rev":"_WQ47Xsq--B",

"hello5":"world1"

"hasMore":true,

"id":"10569",

"count":5,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":5,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.00009655952453613281

"warnings":[]

"cached":false

shell>curl-XDELETE--dump-http://localhost:8529/_api/cursor/10569

ReturnCodes

202:isreturnediftheserverisawareofthecursor.404:isreturnediftheserverisnotawareofthecursor.Itisalsoreturnedifacursorisusedafterithasbeendestroyed.

Examples

"count":true,

"batchSize":2

HTTP/1.1201Created

showresponsebody

AccessingCursors

HTTPInterfaceforAQLQueries

Explainingandparsingqueries

ArangoDBhasanHTTPinterfacetosyntacticallyvalidateAQLqueries.Furthermore,itoffersanHTTPinterfacetoretrievetheexecutionplanforanyvalidAQLquery.

BothfunctionalitiesdonotactuallyexecutethesuppliedAQLquery,butonlyinspectitandreturnmetainformationaboutit.

ExplainanAQLquery

explainanAQLqueryandreturninformationaboutit

POST/_api/explainAJSONobjectdescribingthequeryandqueryparameters.

query:thequerywhichyouwantexplained;Ifthequeryreferencesanybindvariables,thesemustalsobepassedintheattributebindVars.Additionaloptionsforthequerycanbepassedintheoptionsattribute.options:

optimizer.rules(string):anarrayofto-be-includedorto-be-excludedoptimizerrulescanbeputintothisattribute,tellingtheoptimizertoincludeorexcludespecificrules.Todisablearule,prefixitsnamewitha-,toenablearule,prefixitwitha+.Thereisalsoapseudo-ruleall,whichwillmatchalloptimizerrules.maxNumberOfPlans:anoptionalmaximumnumberofplansthattheoptimizerisallowedtogenerate.Settingthisattributetoalowvalueallowstoputacapontheamountofworktheoptimizerdoes.allPlans:ifsettotrue,allpossibleexecutionplanswillbereturned.Thedefaultisfalse,meaningonlytheoptimalplanwillbereturned.

bindVars(object):key/valuepairsrepresentingthebindparameters.

ToexplainhowanAQLquerywouldbeexecutedontheserver,thequerystringcanbesenttotheserverviaanHTTPPOSTrequest.Theserverwillthenvalidatethequeryandcreateanexecutionplanforit.Theexecutionplanwillbereturned,butthequerywillnotbeexecuted.

Theexecutionplanthatisreturnedbytheservercanbeusedtoestimatetheprobableperformanceofthequery.Thoughtheactualperformancewilldependonmanydifferentfactors,theexecutionplannormallycanprovidesomeroughestimatesontheamountofworktheserverneedstodoinordertoactuallyrunthequery.

Bydefault,theexplainoperationwillreturntheoptimalplanaschosenbythequeryoptimizerTheoptimalplanistheplanwiththelowesttotalestimatedcost.Theplanwillbereturnedintheattributeplanoftheresponseobject.IftheoptionallPlansisspecifiedintherequest,theresultwillcontainallplanscreatedbytheoptimizer.Theplanswillthenbereturnedintheattributeplans.

Theresultwillalsocontainanattributewarnings,whichisanarrayofwarningsthatoccurredduringoptimizationorexecutionplancreation.Additionally,astatsattributeiscontainedintheresultwithsomeoptimizerstatistics.IfallPlansissettofalse,theresultwillcontainanattributecacheablethatstateswhetherthequeryresultscanbecachedontheserverifthequeryresultcachewereused.ThecacheableattributeisnotpresentwhenallPlansissettotrue.

EachplanintheresultisaJSONobjectwiththefollowingattributes:

nodes:thearrayofexecutionnodesoftheplan.Thearrayofavailablenodetypescanbefoundhere

estimatedCost:thetotalestimatedcostfortheplan.Iftherearemultipleplans,theoptimizerwillchoosetheplanwiththelowesttotalcost.

collections:anarrayofcollectionsusedinthequery

rules:anarrayofrulestheoptimizerapplied.Anoverviewoftheavailablerulescanbefoundhere

variables:arrayofvariablesusedinthequery(note:thismaycontaininternalvariablescreatedbytheoptimizer)

Example:

AQLQueries

Validquery

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/explain<<EOF

"query":"FORpINproductsRETURNp"

HTTP/1.1200OK

"plan":{

"nodes":[

"type":"SingletonNode",

"dependencies":[],

"id":1,

"estimatedCost":1,

"estimatedNrItems":1

"type":"EnumerateCollectionNode",

"dependencies":[

"id":2,

"estimatedCost":12,

"estimatedNrItems":10,

"database":"_system",

"random":false,

"satellite":false,

"outVariable":{

"id":0,

"name":"p"

"type":"ReturnNode",

"dependencies":[

"id":3,

"estimatedCost":22,

"inVariable":{

"id":0,

"name":"p"

"rules":[],

"collections":[

"name":"products",

"type":"read"

"variables":[

"id":0,

"name":"p"

"estimatedCost":22,

"initialize":true

"cacheable":true,

"warnings":[],

"stats":{

"rulesExecuted":30,

"rulesSkipped":0,

AQLQueries

"plansCreated":1

"error":false,

"code":200

Example:Aplanwithsomeoptimizerrulesapplied

"query":"FORpINproductsLETa=p.idFILTERa==4LETname=p.nameSORTp.idLIMIT1RETURNname"

HTTP/1.1200OK

"plan":{

"nodes":[

"dependencies":[],

"id":1,

"estimatedCost":1,

"type":"IndexNode",

"dependencies":[

"id":11,

"estimatedCost":4.321928094887362,

"satellite":false,

"outVariable":{

"id":0,

"name":"p"

"indexes":[

"id":"11343",

"type":"skiplist",

"fields":[

"unique":false,

"sparse":false,

"deduplicate":true

"condition":{

"type":"n-aryor",

"subNodes":[

"type":"n-aryand",

"subNodes":[

"type":"compare==",

"subNodes":[

"type":"attributeaccess",

"name":"id",

"subNodes":[

"type":"reference",

AQLQueries

"name":"p",

"id":0

"type":"value",

"value":4

"reverse":false

"type":"CalculationNode",

"dependencies":[

"id":4,

"estimatedCost":5.321928094887362,

"expression":{

"type":"compare==",

"subNodes":[

"name":"id",

"subNodes":[

"type":"reference",

"name":"p",

"id":0

"type":"value",

"value":4

"outVariable":{

"id":4,

"name":"3"

"canThrow":false,

"expressionType":"simple"

"type":"FilterNode",

"dependencies":[

"id":5,

"estimatedCost":6.321928094887362,

"inVariable":{

"id":4,

"name":"3"

"type":"LimitNode",

"dependencies":[

"id":9,

"estimatedCost":7.321928094887362,

"offset":0,

"limit":1,

"fullCount":false

AQLQueries

"dependencies":[

"id":6,

"estimatedCost":8.321928094887362,

"expression":{

"name":"name",

"subNodes":[

"type":"reference",

"name":"p",

"id":0

"outVariable":{

"id":2,

"name":"name"

"canThrow":false,

"expressionType":"attribute"

"dependencies":[

"id":10,

"estimatedCost":9.321928094887362,

"inVariable":{

"id":2,

"name":"name"

"rules":[

"move-calculations-up",

"remove-redundant-calculations",

"remove-unnecessary-calculations",

"move-calculations-up-2",

"use-indexes",

"use-index-for-sort",

"remove-unnecessary-calculations-2",

"move-calculations-down"

"collections":[

"name":"products",

"type":"read"

"variables":[

"id":6,

"name":"5"

"id":4,

"name":"3"

"id":2,

"name":"name"

"id":1,

"name":"a"

"id":0,

AQLQueries

"name":"p"

"estimatedCost":9.321928094887362,

"initialize":true

"cacheable":true,

"warnings":[],

"stats":{

"rulesExecuted":30,

"rulesSkipped":0,

"plansCreated":1

"error":false,

"code":200

Example:Usingsomeoptions

"query":"FORpINproductsLETa=p.idFILTERa==4LETname=p.nameSORTp.idLIMIT1RETURNname",

"options":{

"maxNumberOfPlans":2,

"allPlans":true,

"optimizer":{

"rules":[

"-all",

"+use-index-for-sort",

"+use-index-range"

HTTP/1.1200OK

"plans":[

"nodes":[

"dependencies":[],

"id":1,

"estimatedCost":1,

"type":"IndexNode",

"dependencies":[

"id":11,

"estimatedCost":11,

"satellite":false,

"outVariable":{

"id":0,

"name":"p"

"indexes":[

"id":"11389",

AQLQueries

"type":"skiplist",

"fields":[

"unique":false,

"sparse":false,

"deduplicate":true

"condition":{

"reverse":false

"dependencies":[

"id":3,

"estimatedCost":21,

"expression":{

"name":"id",

"subNodes":[

"type":"reference",

"name":"p",

"id":0

"outVariable":{

"id":1,

"name":"a"

"canThrow":false,

"dependencies":[

"id":4,

"estimatedCost":31,

"expression":{

"type":"compare==",

"subNodes":[

"type":"reference",

"name":"a",

"id":1

"type":"value",

"value":4

"outVariable":{

"id":4,

"name":"3"

"canThrow":false,

"type":"FilterNode",

"dependencies":[

"id":5,

"estimatedCost":41,

AQLQueries

"inVariable":{

"id":4,

"name":"3"

"dependencies":[

"id":6,

"estimatedCost":51,

"expression":{

"name":"name",

"subNodes":[

"type":"reference",

"name":"p",

"id":0

"outVariable":{

"id":2,

"name":"name"

"canThrow":false,

"dependencies":[

"id":7,

"estimatedCost":61,

"expression":{

"name":"id",

"subNodes":[

"type":"reference",

"name":"p",

"id":0

"outVariable":{

"id":6,

"name":"5"

"canThrow":false,

"type":"LimitNode",

"dependencies":[

"id":9,

"estimatedCost":62,

"offset":0,

"limit":1,

"fullCount":false

"dependencies":[

"id":10,

"estimatedCost":63,

AQLQueries

"inVariable":{

"id":2,

"name":"name"

"rules":[

"use-index-for-sort"

"collections":[

"name":"products",

"type":"read"

"variables":[

"id":6,

"name":"5"

"id":4,

"name":"3"

"id":2,

"name":"name"

"id":1,

"name":"a"

"id":0,

"name":"p"

"estimatedCost":63,

"initialize":true

"warnings":[],

"stats":{

"rulesExecuted":1,

"rulesSkipped":29,

"plansCreated":1

"error":false,

"code":200

Example:Returningallplans

"query":"FORpINproductsFILTERp.id==25RETURNp",

"options":{

"allPlans":true

HTTP/1.1200OK

"plans":[

AQLQueries

"nodes":[

"dependencies":[],

"id":1,

"estimatedCost":1,

"type":"IndexNode",

"dependencies":[

"id":6,

"estimatedCost":1.99,

"satellite":false,

"outVariable":{

"id":0,

"name":"p"

"indexes":[

"id":"11305",

"type":"hash",

"fields":[

"selectivityEstimate":1,

"unique":false,

"sparse":false,

"deduplicate":true

"condition":{

"type":"n-aryor",

"subNodes":[

"type":"n-aryand",

"subNodes":[

"type":"compare==",

"subNodes":[

"name":"id",

"subNodes":[

"type":"reference",

"name":"p",

"id":0

"type":"value",

"value":25

"reverse":false

"dependencies":[

"id":5,

AQLQueries

"inVariable":{

"id":0,

"name":"p"

"rules":[

"use-indexes",

"remove-filter-covered-by-index",

"remove-unnecessary-calculations-2"

"collections":[

"name":"products",

"type":"read"

"variables":[

"id":2,

"name":"1"

"id":0,

"name":"p"

"initialize":true

"warnings":[],

"stats":{

"rulesExecuted":30,

"rulesSkipped":0,

"plansCreated":1

"error":false,

"code":200

Example:Aquerythatproducesawarning

"query":"FORiIN1..10RETURN1/0"

HTTP/1.1200OK

"plan":{

"nodes":[

"dependencies":[],

"id":1,

"estimatedCost":1,

"dependencies":[

AQLQueries

"id":2,

"estimatedCost":2,

"expression":{

"type":"range",

"subNodes":[

"type":"value",

"value":1

"type":"value",

"value":10

"outVariable":{

"id":2,

"name":"1"

"canThrow":false,

"dependencies":[

"id":4,

"estimatedCost":3,

"expression":{

"type":"value",

"value":null

"outVariable":{

"id":4,

"name":"3"

"canThrow":false,

"expressionType":"json"

"type":"EnumerateListNode",

"dependencies":[

"id":3,

"estimatedCost":13,

"inVariable":{

"id":2,

"name":"1"

"outVariable":{

"id":0,

"name":"i"

"dependencies":[

"id":5,

"estimatedCost":23,

"inVariable":{

"id":4,

"name":"3"

"rules":[

"move-calculations-up-2"

AQLQueries

"collections":[],

"variables":[

"id":4,

"name":"3"

"id":2,

"name":"1"

"id":0,

"name":"i"

"estimatedCost":23,

"initialize":true

"cacheable":false,

"warnings":[

"code":1562,

"message":"divisionbyzero"

"stats":{

"rulesExecuted":30,

"rulesSkipped":0,

"plansCreated":1

"error":false,

"code":200

Example:Invalidquery(missingbindparameter)

"query":"FORpINproductsFILTERp.id==@idLIMIT2RETURNp.n"

"error":true,

"errorMessage":"novaluespecifiedfordeclaredbindparameter'id'(whileparsing)",

"code":400,

"errorNum":1551

Example:ThedatareturnedintheplanattributeoftheresultcontainsoneelementperAQLtop-levelstatement(i.e.FOR,RETURN,FILTERetc.).Ifthequeryoptimizerremovedsomeunnecessarystatements,theresultmightalsocontainlesselementsthanthereweretop-levelstatementsintheAQLquery.

Thefollowingexampleshowsaquerywithanon-sensiblefilterconditionthattheoptimizerhasremovedsothattherearelesstop-levelstatements.

AQLQueries

{"query":"FORiIN[1,2,3]FILTER1==2RETURNi"}

HTTP/1.1200OK

"plan":{

"nodes":[

"dependencies":[],

"id":1,

"estimatedCost":1,

"dependencies":[

"id":2,

"estimatedCost":2,

"expression":{

"type":"array",

"subNodes":[

"type":"value",

"value":1

"type":"value",

"value":2

"type":"value",

"value":3

"outVariable":{

"id":2,

"name":"1"

"canThrow":false,

"expressionType":"json"

"type":"NoResultsNode",

"dependencies":[

"id":7,

"type":"EnumerateListNode",

"dependencies":[

"id":3,

"inVariable":{

"id":2,

"name":"1"

"outVariable":{

"id":0,

"name":"i"

AQLQueries

"dependencies":[

"id":6,

"inVariable":{

"id":0,

"name":"i"

"rules":[

"move-filters-up",

"remove-unnecessary-filters",

"remove-unnecessary-calculations"

"collections":[],

"variables":[

"id":4,

"name":"3"

"id":2,

"name":"1"

"id":0,

"name":"i"

"initialize":true

"cacheable":true,

"warnings":[],

"stats":{

"rulesExecuted":30,

"rulesSkipped":0,

"plansCreated":1

"error":false,

"code":200

"query":"FORpINproductsRETURNp"

HTTP/1.1200OK

showresponsebodyAplanwithsomeoptimizerrulesapplied

"query":"FORpINproductsLETa=p.idFILTERa==4LETname=p.nameSORTp.id

LIMIT1RETURNname"

AQLQueries

HTTP/1.1200OK

showresponsebodyUsingsomeoptions

"query":"FORpINproductsLETa=p.idFILTERa==4LETname=p.nameSORTp.id

LIMIT1RETURNname",

"options":{

"maxNumberOfPlans":2,

"allPlans":true,

"optimizer":{

"rules":[

"-all",

"+use-index-for-sort",

"+use-index-range"

HTTP/1.1200OK

showresponsebodyReturningallplans

"query":"FORpINproductsFILTERp.id==25RETURNp",

"options":{

"allPlans":true

HTTP/1.1200OK

showresponsebodyAquerythatproducesawarning

AQLQueries

"query":"FORiIN1..10RETURN1/0"

HTTP/1.1200OK

showresponsebodyInvalidquery(missingbindparameter)

"query":"FORpINproductsFILTERp.id==@idLIMIT2RETURNp.n"

showresponsebodyThedatareturnedintheplanattributeoftheresultcontainsoneelementperAQLtop-levelstatement(i.e.FOR,RETURN,FILTERetc.).Ifthequeryoptimizerremovedsomeunnecessarystatements,theresultmightalsocontainlesselementsthanthereweretop-levelstatementsintheAQLquery.Thefollowingexampleshowsaquerywithanon-sensiblefilterconditionthattheoptimizerhasremovedsothattherearelesstop-levelstatements.

{"query":"FORiIN[1,2,3]FILTER1==2RETURNi"}

HTTP/1.1200OK

showresponsebody

ParseanAQLquery

parseanAQLqueryandreturninformationaboutit

POST/_api/query

Thisendpointisforqueryvalidationonly.Toactuallyquerythedatabase,see/api/cursor.

query:Tovalidateaquerystringwithoutexecutingit,thequerystringcanbepassedtotheserverviaanHTTPPOSTrequest.

Example:aValidquery

AQLQueries

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/query<<EOF

{"query":"FORpINproductsFILTERp.name==@nameLIMIT2RETURNp.n"}

HTTP/1.1200OK

"error":false,

"code":200,

"parsed":true,

"collections":[

"products"

"bindVars":[

"name"

"ast":[

"type":"root",

"subNodes":[

"type":"for",

"subNodes":[

"type":"variable",

"name":"p",

"id":0

"type":"collection",

"name":"products"

"type":"filter",

"subNodes":[

"type":"compare==",

"subNodes":[

"name":"name",

"subNodes":[

"type":"reference",

"name":"p",

"id":0

"type":"parameter",

"name":"name"

"type":"limit",

"subNodes":[

"type":"value",

"value":0

"type":"value",

"value":2

"type":"return",

AQLQueries

"subNodes":[

"name":"n",

"subNodes":[

"type":"reference",

"name":"p",

"id":0

Example:anInvalidquery

{"query":"FORpINproductsFILTERp.name=@nameLIMIT2RETURNp.n"}

"error":true,

"errorMessage":"syntaxerror,unexpectedassignmentnear'=@nameLIMIT2RETURNp.n'atposition1:33",

"code":400,

"errorNum":1501

ReturnCodes

200:Ifthequeryisvalid,theserverwillrespondwithHTTP200andreturnthenamesofthebindparametersitfoundinthequery(ifany)inthebindVarsattributeoftheresponse.Itwillalsoreturnanarrayofthecollectionsusedinthequeryinthecollectionsattribute.Ifaquerycanbeparsedsuccessfully,theastattributeofthereturnedJSONwillcontaintheabstractsyntaxtreerepresentationofthequery.TheformatoftheastissubjecttochangeinfutureversionsofArangoDB,butitcanbeusedtoinspecthowArangoDBinterpretsagivenquery.Notethattheabstractsyntaxtreewillbereturnedwithoutanyoptimizationsappliedtoit.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,orifthequerycontainsaparseerror.ThebodyoftheresponsewillcontaintheerrordetailsembeddedinaJSONobject.

Examples

aValidquery

{"query":"FORpINproductsFILTERp.name==@nameLIMIT2RETURNp.n"}

HTTP/1.1200OK

showresponsebodyanInvalidquery

AQLQueries

{"query":"FORpINproductsFILTERp.name=@nameLIMIT2RETURNp.n"}

showresponsebody

Querytracking

ArangoDBhasanHTTPinterfaceforretrievingthelistsofcurrentlyexecutingAQLqueriesandthelistofslowAQLqueries.InordertomakemeaningfuluseoftheseAPIs,querytrackingneedstobeenabledinthedatabasetheHTTPrequestisexecutedfor.

ReturnsthepropertiesfortheAQLquerytracking

returnstheconfigurationfortheAQLquerytracking

GET/_api/query/properties

Returnsthecurrentquerytrackingconfiguration.TheconfigurationisaJSONobjectwiththefollowingproperties:

enabled:ifsettotrue,thenquerieswillbetracked.Ifsettofalse,neitherqueriesnorslowquerieswillbetracked.

trackSlowQueries:ifsettotrue,thenslowquerieswillbetrackedinthelistofslowqueriesiftheirruntimeexceedsthevaluesetinslowQueryThreshold.Inorderforslowqueriestobetracked,theenabledpropertymustalsobesettotrue.

trackBindVars:ifsettotrue,thenbindvariablesusedinquerieswillbetracked.

maxSlowQueries:themaximumnumberofslowqueriestokeepinthelistofslowqueries.Ifthelistofslowqueriesisfull,theoldestentryinitwillbediscardedwhenadditionalslowqueriesoccur.

slowQueryThreshold:thethresholdvaluefortreatingaqueryasslow.Aquerywitharuntimegreaterorequaltothisthresholdvaluewillbeputintothelistofslowquerieswhenslowquerytrackingisenabled.ThevalueforslowQueryThresholdisspecifiedinseconds.

maxQueryStringLength:themaximumquerystringlengthtokeepinthelistofqueries.Querystringscanhavearbitrarylengths,andthispropertycanbeusedtosavememoryincaseverylongquerystringsareused.Thevalueisspecifiedinbytes.

ReturnCodes

200:Isreturnedifpropertieswereretrievedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,

ChangesthepropertiesfortheAQLquerytracking

changestheconfigurationfortheAQLquerytracking

PUT/_api/query/properties

maxSlowQueries:Themaximumnumberofslowqueriestokeepinthelistofslowqueries.Ifthelistofslowqueriesisfull,theoldestentryinitwillbediscardedwhenadditionalslowqueriesoccur.slowQueryThreshold:Thethresholdvaluefortreatingaqueryasslow.Aquerywitharuntimegreaterorequaltothisthresholdvaluewillbeputintothelistofslowquerieswhenslowquerytrackingisenabled.ThevalueforslowQueryThresholdisspecifiedinseconds.enabled:Ifsettotrue,thenquerieswillbetracked.Ifsettofalse,neitherqueriesnorslowquerieswillbetracked.maxQueryStringLength:Themaximumquerystringlengthtokeepinthelistofqueries.Querystringscanhavearbitrarylengths,andthispropertycanbeusedtosavememoryincaseverylongquerystringsareused.Thevalueisspecifiedinbytes.trackSlowQueries:Ifsettotrue,thenslowquerieswillbetrackedinthelistofslowqueriesiftheirruntimeexceedsthevalueset

AQLQueries

inslowQueryThreshold.Inorderforslowqueriestobetracked,theenabledpropertymustalsobesettotrue.

trackBindVars:Ifsettotrue,thenthebindvariablesusedinquerieswillbetrackedalongwithqueries.

ThepropertiesneedtobepassedintheattributepropertiesinthebodyoftheHTTPrequest.propertiesneedstobeaJSONobject.

Afterthepropertieshavebeenchanged,thecurrentsetofpropertieswillbereturnedintheHTTPresponse.

ReturnCodes

200:Isreturnedifthepropertieswerechangedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,

ReturnsthecurrentlyrunningAQLqueries

returnsalistofcurrentlyrunningAQLqueries

GET/_api/query/current

ReturnsanarraycontainingtheAQLqueriescurrentlyrunningintheselecteddatabase.EachqueryisaJSONobjectwiththefollowingattributes:

id:thequery'sid

query:thequerystring(potentiallytruncated)

bindVars:thebindparametervaluesusedbythequery

started:thedateandtimewhenthequerywasstarted

runTime:thequery'sruntimeuptothepointthelistofquerieswasqueried

state:thequery'scurrentexecutionstate(asastring)

ReturnCodes

200:Isreturnedwhenthelistofqueriescanberetrievedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,

ReturnsthelistofslowAQLqueries

returnsalistofslowrunningAQLqueries

GET/_api/query/slow

ReturnsanarraycontainingthelastAQLqueriesthatarefinishedandhaveexceededtheslowquerythresholdintheselecteddatabase.ThemaximumamountofqueriesinthelistcanbecontrolledbysettingthequerytrackingpropertymaxSlowQueries.ThethresholdfortreatingaqueryasslowcanbeadjustedbysettingthequerytrackingpropertyslowQueryThreshold.

EachqueryisaJSONobjectwiththefollowingattributes:

id:thequery'sid

query:thequerystring(potentiallytruncated)

bindVars:thebindparametervaluesusedbythequery

started:thedateandtimewhenthequerywasstarted

runTime:thequery'stotalruntime

state:thequery'scurrentexecutionstate(willalwaysbe"finished"forthelistofslowqueries)

ReturnCodes

200:Isreturnedwhenthelistofqueriescanberetrievedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,

ClearsthelistofslowAQLqueries

AQLQueries

clearsthelistofslowAQLqueries

DELETE/_api/query/slow

ClearsthelistofslowAQLqueries

ReturnCodes

200:TheserverwillrespondwithHTTP200whenthelistofquerieswasclearedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest.

Killingqueries

RunningAQLqueriescanalsobekilledontheserver.ArangoDBprovidesakillfacilityviaanHTTPinterface.Tokillarunningquery,itsid(asreturnedforthequeryinthelistofcurrentlyrunningqueries)mustbespecified.Thekillflagofthequerywillthenbeset,andthequerywillbeabortedassoonasitreachesacancelationpoint.

KillsarunningAQLquery

killsanAQLquery

DELETE/_api/query/{query-id}

PathParameters

query-id(required):Theidofthequery.

Killsarunningquery.Thequerywillbeterminatedatthenextcancelationpoint.

ReturnCodes

200:TheserverwillrespondwithHTTP200whenthequerywasstillrunningwhenthekillrequestwasexecutedandthequery'skillflagwasset.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest.404:TheserverwillrespondwithHTTP404whennoquerywiththespecifiedidwasfound.

AQLQueries

HTTPInterfacefortheAQLquerycacheThissectiondescribestheAPImethodsforcontrollingtheAQLquerycache.

ClearsanyresultsintheAQLquerycache

clearstheAQLquerycache

DELETE/_api/query-cache

clearsthequerycache

ReturnCodes

200:TheserverwillrespondwithHTTP200whenthecachewasclearedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest.

ReturnstheglobalpropertiesfortheAQLquerycache

returnstheglobalconfigurationfortheAQLquerycache

GET/_api/query-cache/properties

ReturnstheglobalAQLquerycacheconfiguration.TheconfigurationisaJSONobjectwiththefollowingproperties:

mode:themodetheAQLquerycacheoperatesin.Themodeisoneofthefollowingvalues:off,onordemand.

maxResults:themaximumnumberofqueryresultsthatwillbestoredperdatabase-specificcache.

ReturnCodes

200:Isreturnedifthepropertiescanberetrievedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,

GloballyadjuststheAQLqueryresultcacheproperties

changestheconfigurationfortheAQLquerycache

PUT/_api/query-cache/properties

Afterthepropertieshavebeenchanged,thecurrentsetofpropertieswillbereturnedintheHTTPresponse.

Note:changingthepropertiesmayinvalidateallresultsinthecache.TheglobalpropertiesforAQLquerycache.ThepropertiesneedtobepassedintheattributepropertiesinthebodyoftheHTTPrequest.propertiesneedstobeaJSONobjectwiththefollowingproperties:

mode:themodetheAQLquerycacheshouldoperatein.Possiblevaluesareoff,onordemand.maxResults:themaximumnumberofqueryresultsthatwillbestoredperdatabase-specificcache.

ReturnCodes

200:Isreturnedifthepropertieswerechangedsuccessfully.400:TheserverwillrespondwithHTTP400incaseofamalformedrequest,

AQLQueryCache

HTTPInterfaceforAQLUserFunctionsManagement

ThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingAQLuserfunctions.AQLuserfunctionsareameanstoextendthefunctionalityofArangoDB'squerylanguage(AQL)withuser-definedJavaScriptcode.

ForanoverviewofhowAQLuserfunctionsandtheirimplications,pleaserefertotheExtendingAQLchapter.

TheHTTPinterfaceprovidesanAPIforadding,deleting,andlistingpreviouslyregisteredAQLuserfunctions.

Alluserfunctionsmanagedthroughthisinterfacewillbestoredinthesystemcollection_aqlfunctions.Documentsinthiscollectionshouldnotbeaccesseddirectly,butonlyviathededicatedinterfaces.

CreateAQLuserfunction

createanewAQLuserfunction

POST/_api/aqlfunction

isDeterministic:anoptionalbooleanvaluetoindicatethatthefunctionresultsarefullydeterministic(functionreturnvaluesolelydependsontheinputvalueandreturnvalueisthesameforrepeatedcallswithsameinput).TheisDeterministicattributeiscurrentlynotusedbutmaybeusedlaterforoptimisations.code:astringrepresentationofthefunctionbody.name:thefullyqualifiednameoftheuserfunctions.

Incaseofsuccess,thereturnedJSONobjecthasthefollowingproperties:

error:booleanflagtoindicatethatanerroroccurred(falseinthiscase)

ThebodyoftheresponsewillcontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/aqlfunction<<EOF

"name":"myfunctions::temperature::celsiustofahrenheit",

"code":"function(celsius){returncelsius*1.8+32;}"

HTTP/1.1201Created

"error":false,

"code":201

ReturnCodes

200:Ifthefunctionalreadyexistedandwasreplacedbythecall,theserverwillrespondwithHTTP200.201:Ifthefunctioncanberegisteredbytheserver,theserverwillrespondwithHTTP201.400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest,theserverwillrespondwithHTTP400.

Examples

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/aqlfunction<<EOF

HTTP/1.1201Created

"error":false,

"code":201

RemoveexistingAQLuserfunction

removeanexistingAQLuserfunction

DELETE/_api/aqlfunction/{name}

PathParameters

name(required):thenameoftheAQLuserfunction.

QueryParameters

group(optional):Ifsettotrue,thenthefunctionnameprovidedinnameistreatedasanamespaceprefix,andallfunctionsinthespecifiednamespacewillbedeleted.Ifsettofalse,thefunctionnameprovidedinnamemustbefullyqualified,includinganynamespaces.

RemovesanexistingAQLuserfunction,identifiedbyname.

Incaseofsuccess,thereturnedJSONobjecthasthefollowingproperties:

Example:deletesafunction:

shell>curl-XDELETE--dump-http://localhost:8529/_api/aqlfunction/square::x::y

HTTP/1.1200OK

"error":false,

"code":200

Example:functionnotfound:

shell>curl-XDELETE--dump-http://localhost:8529/_api/aqlfunction/myfunction::x::y

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":1582,

"errorMessage":"userfunction'%s()'notfound"

ReturnCodes

200:Ifthefunctioncanberemovedbytheserver,theserverwillrespondwithHTTP200.400:Iftheuserfunctionnameismalformed,theserverwillrespondwithHTTP400.404:Ifthespecifieduseruserfunctiondoesnotexist,theserverwillrespondwithHTTP404.

Examples

deletesafunction:

shell>curl-XDELETE--dump-http://localhost:8529/_api/aqlfunction/square::x::y

HTTP/1.1200OK

"error":false,

"code":200

functionnotfound:

shell>curl-XDELETE--dump-http://localhost:8529/_api/aqlfunction/myfunction::x::y

HTTP/1.1404NotFound

showresponsebody

ReturnregisteredAQLuserfunctions

getsallreqisteredAQLuserfunctions

GET/_api/aqlfunction

QueryParameters

namespace(optional):ReturnsallregisteredAQLuserfunctionsfromnamespacenamespace.

ReturnsallregisteredAQLuserfunctions.

ThecallwillreturnaJSONarraywithalluserfunctionsfound.Eachuserfunctionwillatleasthavethefollowingattributes:

name:Thefullyqualifiednameoftheuserfunction

code:Astringrepresentationofthefunctionbody

Example:

shell>curl--dump-http://localhost:8529/_api/aqlfunction

HTTP/1.1200OK

ReturnCodes

200:ifsuccessHTTP200isreturned.

Examples

shell>curl--dump-http://localhost:8529/_api/aqlfunction

HTTP/1.1200OK

HTTPInterfaceforSimpleQueries

SimpleQueries

ThisisanintroductiontoArangoDB'sHTTPinterfaceforsimplequeries.

Simplequeriescanbeusedifthequeryconditionisstraightforwardsimple,i.e.,adocumentreference,alldocuments,aquery-by-example,orasimplegeoquery.Inasimplequeryyoucanspecifyexactlyonecollectionandonecondition.Theresultcanthenbesortedandcanbesplitintopages.

WorkingwithSimplesQueriesusingHTTPTolimittheamountofresultstobetransferredinonebatch,simplequeriessupportabatchSizeparameterthatcanoptionallybeusedtotelltheservertolimitthenumberofresultstobetransferredinonebatchtoacertainvalue.Ifthequeryhasmoreresultsthanweretransferredinonego,moreresultsarewaitingontheserversotheycanbefetchedsubsequently.IfnovalueforthebatchSizeparameterisspecified,theserverwilluseareasonabledefaultvalue.

Iftheserverhasmoredocumentsthanshouldbereturnedinasinglebatch,theserverwillsetthehasMoreattributeintheresult.Itwillalsoreturntheidoftheserver-sidecursorintheidattributeintheresult.ThisidcanbeusedwiththecursorAPItofetchanyoutstandingresultsfromtheserveranddisposetheserver-sidecursorafterwards.

Returnalldocuments

returnsalldocumentsofacollection

PUT/_api/simple/all

Containsthequery.

Returnsalldocumentsofacollections.ThecallexpectsaJSONobjectasbodywiththefollowingattributes:

collection:Thenameofthecollectiontoquery.

skip:Thenumberofdocumentstoskipinthequery(optional).

limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)

Returnsacursorcontainingtheresult,seeHttpCursorfordetails.

Example:Limittheamountofdocumentsusinglimit

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/all<<EOF

{"collection":"products","skip":2,"limit":2}

HTTP/1.1201Created

"result":[

"_key":"12142",

"_rev":"_WQ47fae--_",

"Hello1":"World1"

"_key":"12155",

SimpleQueries

"_rev":"_WQ47fae--H",

"Hello5":"World5"

"hasMore":false,

"count":2,

"cached":false,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":4,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.00009989738464355469

"warnings":[]

"error":false,

"code":201

Example:UsingabatchSizevalue

{"collection":"products","batchSize":3}

HTTP/1.1201Created

"error":false,

"code":201,

"result":[

"_key":"12113",

"_rev":"_WQ47fZ2--_",

"Hello1":"World1"

"_key":"12120",

"_rev":"_WQ47fZ6--B",

"Hello3":"World3"

"_key":"12123",

"_rev":"_WQ47fZ6--D",

"Hello4":"World4"

"hasMore":true,

"id":"12129",

"count":5,

"extra":{

"stats":{

"writesExecuted":0,

"writesIgnored":0,

"scannedFull":5,

"scannedIndex":0,

"filtered":0,

"httpRequests":0,

"executionTime":0.00010585784912109375

SimpleQueries

"warnings":[]

"cached":false

ReturnCodes

201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.

Examples

Limittheamountofdocumentsusinglimit

{"collection":"products","skip":2,"limit":2}

HTTP/1.1201Created

showresponsebodyUsingabatchSizevalue

{"collection":"products","batchSize":3}

HTTP/1.1201Created

showresponsebody

Simplequeryby-example

returnsalldocumentsofacollectionmatchingagivenexample

PUT/_api/simple/by-example

skip:Thenumberofdocumentstoskipinthequery(optional).batchSize:maximumnumberofresultdocumentstobetransferredfromtheservertotheclientinoneroundtrip.Ifthisattributeisnotset,aserver-controlleddefaultvaluewillbeused.AbatchSizevalueof0isdisallowed.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)example:Theexampledocument.collection:Thenameofthecollectiontoquery.

Thiswillfindalldocumentsmatchingagivenexample.

Example:

SimpleQueries

Matchinganattribute

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example<<EOF

"example":{

HTTP/1.1201Created

"result":[

"_key":"12208",

"_rev":"_WQ47fbm--_",

"k":2,

"_key":"12202",

"_rev":"_WQ47fbi--B",

"_key":"12198",

"_rev":"_WQ47fbi--_",

"k":1,

"_key":"12205",

"_rev":"_WQ47fbi--D",

"hasMore":false,

"count":4,

"error":false,

"code":201

Example:Matchinganattributewhichisasub-document

"example":{

"a.j":1

SimpleQueries

HTTP/1.1201Created

"result":[

"_key":"12228",

"_rev":"_WQ47fcK--B",

"_key":"12224",

"_rev":"_WQ47fcK--_",

"k":1,

"hasMore":false,

"count":2,

"error":false,

"code":201

Example:Matchinganattributewithinasub-document

"example":{

HTTP/1.1201Created

"result":[

"_key":"12254",

"_rev":"_WQ47fcq--B",

"hasMore":false,

"count":1,

"error":false,

"code":201

ReturnCodes

SimpleQueries

Examples

Matchinganattribute

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/by-example

"example":{

HTTP/1.1201Created

showresponsebodyMatchinganattributewhichisasub-document

"example":{

"a.j":1

HTTP/1.1201Created

showresponsebodyMatchinganattributewithinasub-document

"example":{

SimpleQueries

HTTP/1.1201Created

showresponsebody

Finddocumentsmatchinganexample

returnsonedocumentofacollectionmatchingagivenexample

PUT/_api/simple/first-example

example:Theexampledocument.collection:Thenameofthecollectiontoquery.

Thiswillreturnthefirstdocumentmatchingagivenexample.

ReturnsaresultcontainingthedocumentorHTTP404ifnodocumentmatchedtheexample.

Ifmorethanonedocumentinthecollectionmatchesthespecifiedexample,onlyoneofthesedocumentswillbereturned,anditisundefinedwhichofthematchingdocumentsisreturned.

Example:Ifamatchingdocumentwasfound

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-example<<EOF

"example":{

HTTP/1.1200OK

"document":{

"_key":"12286",

"_rev":"_WQ47fdO--F",

"k":2,

"error":false,

"code":200

Example:Ifnodocumentwasfound

SimpleQueries

"example":{

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":404,

"errorMessage":"nomatch"

ReturnCodes

200:isreturnedwhenthequerywassuccessfullyexecuted.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.

Examples

Ifamatchingdocumentwasfound

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/first-

example<<EOF

"example":{

HTTP/1.1200OK

showresponsebodyIfnodocumentwasfound

example<<EOF

"example":{

HTTP/1.1404NotFound

SimpleQueries

showresponsebody

Finddocumentsbytheirkeys

fetchesmultipledocumentsbytheirkeys

PUT/_api/simple/lookup-by-keys

keys(string):arraywiththe_keysofdocumentstoremove.collection:Thenameofthecollectiontolookinforthedocuments

Looksupthedocumentsinthespecifiedcollectionusingthearrayofkeysprovided.Alldocumentsforwhichamatchingkeywasspecifiedinthekeysarrayandthatexistinthecollectionwillbereturned.Keysforwhichnodocumentcanbefoundintheunderlyingcollectionareignored,andnoexceptionwillbethrownforthem.

ThebodyoftheresponsecontainsaJSONobjectwithadocumentsattribute.Thedocumentsattributeisanarraycontainingthematchingdocuments.Theorderinwhichmatchingdocumentsarepresentintheresultarrayisunspecified.

Example:Lookingupexistingdocuments

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/lookup-by-keys<<EOF

"keys":[

"test0",

"test1",

"test2",

"test3",

"test4",

"test5",

"test6",

"test7",

"test8",

"test9"

"collection":"test"

HTTP/1.1200OK

"documents":[

"_key":"test0",

"_id":"test/test0",

"_rev":"_WQ47ffG--_",

"value":0

"_key":"test1",

"_id":"test/test1",

"_rev":"_WQ47ffK--_",

"value":1

"_key":"test2",

"_id":"test/test2",

"_rev":"_WQ47ffK--B",

"value":2

"_key":"test3",

"_id":"test/test3",

"_rev":"_WQ47ffK--D",

SimpleQueries

"value":3

"_key":"test4",

"_id":"test/test4",

"_rev":"_WQ47ffK--F",

"value":4

"_key":"test5",

"_id":"test/test5",

"_rev":"_WQ47ffK--H",

"value":5

"_key":"test6",

"_id":"test/test6",

"_rev":"_WQ47ffK--J",

"value":6

"_key":"test7",

"_id":"test/test7",

"_rev":"_WQ47ffK--L",

"value":7

"_key":"test8",

"_id":"test/test8",

"_rev":"_WQ47ffK--N",

"value":8

"_key":"test9",

"_id":"test/test9",

"_rev":"_WQ47ffO--_",

"value":9

"error":false,

"code":200

Example:Lookingupnon-existingdocuments

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/lookup-by-keys<<EOF

"keys":[

"foo",

"bar",

"collection":"test"

HTTP/1.1200OK

"documents":[],

"error":false,

"code":200

ReturnCodes

200:isreturnediftheoperationwascarriedoutsuccessfully.

SimpleQueries

404:isreturnedifthecollectionwasnotfound.Theresponsebodycontainsanerrordocumentinthiscase.405:isreturnediftheoperationwascalledwithadifferentHTTPMETHODthanPUT.

Examples

Lookingupexistingdocuments

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/lookup-by-

keys<<EOF

"keys":[

"test0",

"test1",

"test2",

"test3",

"test4",

"test5",

"test6",

"test7",

"test8",

"test9"

"collection":"test"

HTTP/1.1200OK

showresponsebodyLookingupnon-existingdocuments

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/lookup-by-

keys<<EOF

"keys":[

"foo",

"bar",

"collection":"test"

HTTP/1.1200OK

showresponsebody

Returnarandomdocument

returnsarandomdocumentfromacollection

SimpleQueries

PUT/_api/simple/any

Returnsarandomdocumentfromacollection.ThecallexpectsaJSONobjectasbodywiththefollowingattributes:

collection:Theidentifierornameofthecollectiontoquery.ReturnsaJSONobjectwiththedocumentstoredintheattributedocumentifthecollectioncontainsatleastonedocument.Ifthecollectionisempty,thedocumentattrbutecontainsnull.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/any<<EOF

HTTP/1.1200OK

"document":{

"_key":"12170",

"_rev":"_WQ47fbC--_",

"Hello1":"World1"

"error":false,

"code":200

ReturnCodes

Examples

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/any<<EOF

HTTP/1.1200OK

showresponsebody

Removedocumentsbytheirkeys

removesmultipledocumentsbytheirkeys

PUT/_api/simple/remove-by-keys

keys(string):arraywiththe_keysofdocumentstoremove.options:

SimpleQueries

returnOld:ifsettotrueandsilentaboveisfalse,thentheaboveinformationabouttheremoveddocumentscontainsthecompleteremoveddocuments.silent:ifsettofalse,thentheresultwillcontainanadditionalattributeoldwhichcontainsanarraywithoneentryforeachremoveddocument.Bydefault,theseentrieswillhavethe_id,_keyand_revattributes.waitForSync:ifsettotrue,thenallremovaloperationswillinstantlybesynchronizedtodisk.Ifthisisnotspecified,thenthecollection'sdefaultsyncbehaviorwillbeapplied.

collection:Thenameofthecollectiontolookinforthedocumentstoremove

Looksupthedocumentsinthespecifiedcollectionusingthearrayofkeysprovided,andremovesalldocumentsfromthecollectionwhosekeysarecontainedinthekeysarray.Keysforwhichnodocumentcanbefoundintheunderlyingcollectionareignored,andnoexceptionwillbethrownforthem.

ThebodyoftheresponsecontainsaJSONobjectwithinformationhowmanydocumentswereremoved(andhowmanywerenot).Theremovedattributewillcontainthenumberofactuallyremoveddocuments.Theignoredattributewillcontainthenumberofkeysintherequestforwhichnomatchingdocumentcouldbefound.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-keys<<EOF

"keys":[

"test0",

"test1",

"test2",

"test3",

"test4",

"test5",

"test6",

"test7",

"test8",

"test9"

"collection":"test"

HTTP/1.1200OK

"removed":10,

"ignored":0,

"error":false,

"code":200

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-keys<<EOF

"keys":[

"foo",

"bar",

"collection":"test"

HTTP/1.1200OK

SimpleQueries

"removed":0,

"ignored":3,

"error":false,

"code":200

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-

keys<<EOF

"keys":[

"test0",

"test1",

"test2",

"test3",

"test4",

"test5",

"test6",

"test7",

"test8",

"test9"

"collection":"test"

HTTP/1.1200OK

showresponsebody

keys<<EOF

"keys":[

"foo",

"bar",

"collection":"test"

HTTP/1.1200OK

showresponsebody

Removedocumentsbyexample

removesalldocumentsofacollectionthatmatchanexample

PUT/_api/simple/remove-by-example

SimpleQueries

example:Anexampledocumentthatallcollectiondocumentsarecomparedagainst.collection:Thenameofthecollectiontoremovefrom.options:

limit:anoptionalvaluethatdetermineshowmanydocumentstodeleteatmost.Iflimitisspecifiedbutislessthanthenumberofdocumentsinthecollection,itisundefinedwhichofthedocumentswillbedeleted.waitForSync:ifsettotrue,thenallremovaloperationswillinstantlybesynchronizedtodisk.Ifthisisnotspecified,thenthecollection'sdefaultsyncbehaviorwillbeapplied.

Thiswillfindalldocumentsinthecollectionthatmatchthespecifiedexampleobject.

Note:thelimitattributeisnotsupportedonshardedcollections.Usingitwillresultinanerror.

Returnsthenumberofdocumentsthatweredeleted.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/remove-by-example<<EOF

"example":{

HTTP/1.1200OK

"deleted":1,

"error":false,

"code":200

Example:UsingParameter:waitForSyncandlimit

"example":{

"waitForSync":true,

"limit":2

HTTP/1.1200OK

"deleted":1,

"error":false,

"code":200

SimpleQueries

Example:UsingParameter:waitForSyncandlimitwithnewsignature

"example":{

"options":{

"waitForSync":true,

"limit":2

HTTP/1.1200OK

"deleted":1,

"error":false,

"code":200

example<<EOF

"example":{

HTTP/1.1200OK

showresponsebodyUsingParameter:waitForSyncandlimit

example<<EOF

"example":{

"waitForSync":true,

"limit":2

SimpleQueries

HTTP/1.1200OK

showresponsebodyUsingParameter:waitForSyncandlimitwithnewsignature

example<<EOF

"example":{

"options":{

"waitForSync":true,

"limit":2

HTTP/1.1200OK

showresponsebody

Replacedocumentsbyexample

replacesthebodyofalldocumentsofacollectionthatmatchanexample

PUT/_api/simple/replace-by-example

options:limit:anoptionalvaluethatdetermineshowmanydocumentstoreplaceatmost.Iflimitisspecifiedbutislessthanthenumberofdocumentsinthecollection,itisundefinedwhichofthedocumentswillbereplaced.waitForSync:ifsettotrue,thenallremovaloperationswillinstantlybesynchronizedtodisk.Ifthisisnotspecified,thenthecollection'sdefaultsyncbehaviorwillbeapplied.

example:Anexampledocumentthatallcollectiondocumentsarecomparedagainst.collection:Thenameofthecollectiontoreplacewithin.newValue:Thereplacementdocumentthatwillgetinsertedinplaceofthe"old"documents.

Thiswillfindalldocumentsinthecollectionthatmatchthespecifiedexampleobject,andreplacetheentiredocumentbodywiththenewvaluespecified.Notethatdocumentmeta-attributessuchas_id,_key,_from,_toetc.cannotbereplaced.

Returnsthenumberofdocumentsthatwerereplaced.

Example:

SimpleQueries

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/replace-by-example<<EOF

"example":{

"newValue":{

"foo":"bar"

"limit":3

HTTP/1.1200OK

"replaced":1,

"error":false,

"code":200

Example:UsingnewSignatureforattributesWaitForSyncandlimit

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/replace-by-example<<EOF

"example":{

"newValue":{

"foo":"bar"

"options":{

"limit":3,

"waitForSync":true

HTTP/1.1200OK

"replaced":1,

"error":false,

"code":200

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/replace-by-

example<<EOF

"example":{

SimpleQueries

"newValue":{

"foo":"bar"

"limit":3

HTTP/1.1200OK

showresponsebodyUsingnewSignatureforattributesWaitForSyncandlimit

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/replace-by-

example<<EOF

"example":{

"newValue":{

"foo":"bar"

"options":{

"limit":3,

"waitForSync":true

HTTP/1.1200OK

showresponsebody

Updatedocumentsbyexample

partiallyupdatesthebodyofalldocumentsofacollectionthatmatchanexample

PUT/_api/simple/update-by-example

options:keepNull:Thisparametercanbeusedtomodifythebehaviorwhenhandlingnullvalues.Normally,nullvaluesarestoredinthedatabase.BysettingthekeepNullparametertofalse,thisbehaviorcanbechangedsothatallattributesindatawithnullvalueswillberemovedfromtheupdateddocument.mergeObjects:Controlswhetherobjects(notarrays)willbemergedifpresentinboththeexistingandthepatchdocument.Ifsettofalse,thevalueinthepatchdocumentwilloverwritetheexistingdocument'svalue.Ifsettotrue,objectswillbemerged.Thedefaultistrue.limit:anoptionalvaluethatdetermineshowmanydocumentstoupdateatmost.Iflimitisspecifiedbutislessthanthe

SimpleQueries

numberofdocumentsinthecollection,itisundefinedwhichofthedocumentswillbeupdated.waitForSync:ifsettotrue,thenallremovaloperationswillinstantlybesynchronizedtodisk.Ifthisisnotspecified,thenthecollection'sdefaultsyncbehaviorwillbeapplied.

example:Anexampledocumentthatallcollectiondocumentsarecomparedagainst.collection:Thenameofthecollectiontoupdatewithin.newValue:Adocumentcontainingalltheattributestoupdateinthefounddocuments.

Thiswillfindalldocumentsinthecollectionthatmatchthespecifiedexampleobject,andpartiallyupdatethedocumentbodywiththenewvaluespecified.Notethatdocumentmeta-attributessuchas_id,_key,_from,_toetc.cannotbereplaced.

Returnsthenumberofdocumentsthatwereupdated.

Example:usingoldsyntaxforoptions

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/update-by-example<<EOF

"example":{

"newValue":{

"j":22

"limit":3

HTTP/1.1200OK

"updated":1,

"error":false,

"code":200

Example:usingnewsignatureforoptions

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/update-by-example<<EOF

"example":{

"newValue":{

"j":22

"options":{

"limit":3,

"waitForSync":true

SimpleQueries

HTTP/1.1200OK

"updated":1,

"error":false,

"code":200

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/update-by-

example<<EOF

"example":{

"newValue":{

"j":22

"limit":3

HTTP/1.1200OK

showresponsebodyusingnewsignatureforoptions

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/update-by-

example<<EOF

"example":{

"newValue":{

"j":22

"options":{

"limit":3,

"waitForSync":true

SimpleQueries

HTTP/1.1200OK

showresponsebody

Simplerangequery

returnsalldocumentsofacollectionwithinarange

PUT/_api/simple/range

right:Theupperbound.attribute:Theattributepathtocheck.collection:Thenameofthecollectiontoquery.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)closed:Iftrue,useintervalincludingleftandright,otherwiseexcluderight,butincludeleft.skip:Thenumberofdocumentstoskipinthequery(optional).left:Thelowerbound.

Thiswillfindalldocumentswithinagivenrange.Inordertoexecutearangequery,askip-listindexonthequeriedattributemustbepresent.

Note:therangesimplequeryisdeprecatedasofArangoDB2.6.ThefunctionmayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionwithinaspecificrangeistouseanAQLqueryasfollows:

FORdocIN@@collection

FILTERdoc.value>=@left&&doc.value<@right

LIMIT@skip,@limit

RETURNdoc`

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/range<<EOF

"attribute":"i",

"left":2,

"right":4

HTTP/1.1201Created

"result":[

"_key":"12528",

"_rev":"_WQ47fie--B",

"_key":"12531",

"_rev":"_WQ47fie--D",

SimpleQueries

"hasMore":false,

"count":2,

"error":false,

"code":201

ReturnCodes

201:isreturnedifthequerywasexecutedsuccessfully.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocumentinthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknownornosuitableindexfortherangequeryispresent.Theresponsebodycontainsanerrordocumentinthiscase.

Examples

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/range<<EOF

"attribute":"i",

"left":2,

"right":4

HTTP/1.1201Created

showresponsebody

Returnsdocumentsnearacoordinate

returnsalldocumentsofacollectionnearagivenlocation

PUT/_api/simple/near

distance:Ifgiven,theattributekeyusedtoreturnthedistancetothegivencoordinate.(optional).Ifspecified,distancesarereturnedinmeters.skip:Thenumberofdocumentstoskipinthequery.(optional)longitude:Thelongitudeofthecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)collection:Thenameofthecollectiontoquery.latitude:Thelatitudeofthecoordinate.geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)

Thedefaultwillfindatmost100documentsnearthegivencoordinate.Thereturnedarrayissortedaccordingtothedistance,withthenearestdocumentbeingfirstinthereturnarray.Ifthereareneardocumentsofequaldistance,documentsarechosenrandomlyfromthissetuntilthelimitisreached.

Inordertousethenearoperator,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.

SimpleQueries

Note:thenearsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheNEARfunctionasfollows:

FORdocINNEAR(@@collection,@latitude,@longitude,@limit)

RETURNdoc`

Example:Withoutdistance

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/near<<EOF

"latitude":0,

"longitude":0,

"skip":1,

"limit":2

HTTP/1.1201Created

"result":[

"_key":"12441",

"_rev":"_WQ47fgq--D",

"name":"Name/0.002/",

"loc":[

0.002,

"_key":"12435",

"_rev":"_WQ47fgq--_",

"name":"Name/-0.002/",

"loc":[

-0.002,

"hasMore":false,

"count":2,

"error":false,

"code":201

Example:Withdistance

"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

"distance":"distance"

SimpleQueries

HTTP/1.1201Created

"result":[

"distance":222.38985328911744,

"_key":"12486",

"_rev":"_WQ47fhq--D",

"loc":[

-0.002,

"name":"Name/-0.002/"

"distance":222.38985328911744,

"_key":"12492",

"_rev":"_WQ47fhq--H",

"loc":[

0.002,

"name":"Name/0.002/"

"distance":444.779706578235,

"_key":"12483",

"_rev":"_WQ47fhq--B",

"loc":[

-0.004,

"name":"Name/-0.004/"

"hasMore":false,

"count":3,

"error":false,

"code":201

ReturnCodes

Examples

Withoutdistance

"latitude":0,

"longitude":0,

"skip":1,

"limit":2

SimpleQueries

HTTP/1.1201Created

showresponsebodyWithdistance

"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

HTTP/1.1201Created

showresponsebody

Finddocumentswithinaradiusaroundacoordinate

returnsalldocumentsofacollectionwithinagivenradius

PUT/_api/simple/within

distance:Ifgiven,theattributekeyusedtoreturnthedistancetothegivencoordinate.(optional).Ifspecified,distancesarereturnedinmeters.skip:Thenumberofdocumentstoskipinthequery.(optional)longitude:Thelongitudeofthecoordinate.radius:Themaximalradius(inmeters).collection:Thenameofthecollectiontoquery.latitude:Thelatitudeofthecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)

Thiswillfindalldocumentswithinagivenradiusaroundthecoordinate(latitude,longitude).Thereturnedlistissortedbydistance.

Inordertousethewithinoperator,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.

Note:thewithinsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheWITHINfunctionasfollows:

FORdocINWITHIN(@@collection,@latitude,@longitude,@radius,@distanceAttributeName)

RETURNdoc

SimpleQueries

"latitude":0,

"longitude":0,

"skip":1,

"limit":2,

"radius":500

HTTP/1.1201Created

"result":[

"_key":"12854",

"_rev":"_WQ47foi--_",

"name":"Name/0.002/",

"loc":[

0.002,

"_key":"12848",

"_rev":"_WQ47foe--H",

"name":"Name/-0.002/",

"loc":[

-0.002,

"hasMore":false,

"count":2,

"error":false,

"code":201

"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

"distance":"distance",

"radius":300

HTTP/1.1201Created

"result":[

SimpleQueries

"distance":222.38985328911744,

"_key":"12899",

"_rev":"_WQ47fpW--B",

"loc":[

-0.002,

"name":"Name/-0.002/"

"distance":222.38985328911744,

"_key":"12905",

"_rev":"_WQ47fpW--F",

"loc":[

0.002,

"distance":444.779706578235,

"_key":"12896",

"_rev":"_WQ47fpW--_",

"loc":[

-0.004,

"name":"Name/-0.004/"

"hasMore":false,

"count":3,

"error":false,

"code":201

ReturnCodes

Examples

Withoutdistance

"latitude":0,

"longitude":0,

"skip":1,

"limit":2,

"radius":500

HTTP/1.1201Created

SimpleQueries

"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

"radius":300

HTTP/1.1201Created

showresponsebody

Withinrectanglequery

returnsalldocumentsofacollectionwithinarectangle

PUT/_api/simple/within-rectangle

latitude1:Thelatitudeofthefirstrectanglecoordinate.skip:Thenumberofdocumentstoskipinthequery.(optional)latitude2:Thelatitudeofthesecondrectanglecoordinate.longitude2:Thelongitudeofthesecondrectanglecoordinate.longitude1:Thelongitudeofthefirstrectanglecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)collection:Thenameofthecollectiontoquery.geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)

Thiswillfindalldocumentswithinthespecifiedrectangle(determinedbythegivencoordinates(latitude1,longitude1,latitude2,longitude2).

Inordertousethewithin-rectanglequery,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/within-rectangle<<EOF

"latitude1":0,

"longitude1":0,

"latitude2":0.2,

"longitude2":0.2,

"skip":1,

"limit":2

SimpleQueries

HTTP/1.1201Created

"result":[

"_key":"12965",

"_rev":"_WQ47fqO--F",

"name":"Name/0.008/",

"loc":[

0.008,

"_key":"12962",

"_rev":"_WQ47fqO--D",

"name":"Name/0.006/",

"loc":[

0.006,

"hasMore":false,

"count":2,

"error":false,

"code":201

ReturnCodes

Examples

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/within-

rectangle<<EOF

"latitude1":0,

"longitude1":0,

"latitude2":0.2,

"longitude2":0.2,

"skip":1,

"limit":2

HTTP/1.1201Created

showresponsebody

Fulltextindexquery

returnsdocumentsofacollectionasaresultofafulltextquery

SimpleQueries

PUT/_api/simple/fulltext

index:Theidentifierofthefulltext-indextouse.attribute:Theattributethatcontainsthetexts.collection:Thenameofthecollectiontoquery.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)skip:Thenumberofdocumentstoskipinthequery(optional).query:Thefulltextquery.PleaserefertoFulltextqueriesfordetails.

Thiswillfindalldocumentsfromthecollectionthatmatchthefulltextqueryspecifiedinquery.

Inordertousethefulltextoperator,afulltextindexmustbedefinedforthecollectionandthespecifiedattribute.

Note:thefulltextsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheFULLTEXTAQLfunctionasfollows:

FORdocINFULLTEXT(@@collection,@attributeName,@queryString,@limit)

RETURNdoc

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/fulltext<<EOF

"attribute":"text",

"query":"word"

HTTP/1.1201Created

"result":[

"_key":"12326",

"_rev":"_WQ47feO--_",

"text":"thistextcontainsword"

"_key":"12330",

"_rev":"_WQ47feS--_",

"text":"thistextalsohasaword"

"hasMore":false,

"count":2,

"error":false,

"code":201

ReturnCodes

Examples

SimpleQueries

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/fulltext

"attribute":"text",

"query":"word"

HTTP/1.1201Created

showresponsebody

SimpleQueries

HTTPInterfaceforAsyncResultsManagement

RequestExecution

ArangoDBprovidesvariousmethodsofexecutingclientrequests.Clientscanchoosetheappropriatemethodonaper-requestlevelbasedontheirthroughput,controlflow,anddurabilityrequirements.

Blockingexecution

ArangoDBisamulti-threadedserver,allowingtheprocessingofmultipleclientrequestsatthesametime.Communicationhandlingandtheactualworkcanbeperformedbymultipleworkerthreadsinparallel.

ThoughmultipleclientscanconnectandsendtheirrequestsinparalleltoArangoDB,clientsmayneedtowaitfortheirrequeststobeprocessed.

Bydefault,theserverwillfullyprocessanincomingrequestandthenreturntheresulttotheclient.Theclientmustwaitfortheserver'sresponsebeforeitcansendadditionalrequestsovertheconnection.Forclientsthataresingle-threadedornotevent-driven,waitingforthefullserverresponsemaybenon-optimal.

Furthermore,pleasenotethateveniftheclientclosestheHTTPconnection,therequestrunningontheserverwillstillcontinueuntilitiscompleteandonlythennoticethattheclientnolongerlistens.Thusclosingtheconnectiondoesnothelptoabortalongrunningquery!SeebelowunderAsyncExecutionandlaterResultRetrievalandHttpJobPutCancelfordetails.

FireandForget

Tomitigateclientblockingissues,ArangoDBsinceversion1.4.offersagenericmechanismfornon-blockingrequests:ifclientsaddtheHTTPheaderx-arango-async:truetotheirrequests,ArangoDBwillputtherequestintoanin-memorytaskqueueandreturnanHTTP202(accepted)responsetotheclientinstantly.Theserverwillexecutethetasksfromthequeueasynchronously,decouplingtheclientrequestsandtheactualwork.

Thisallowsformuchhigherthroughputthanifclientswouldwaitfortheserver'sresponse.Thedownsideisthattheresponsethatissenttotheclientisalwaysthesame(agenericHTTP202)andclientscannotmakeadecisionbasedontheactualoperation'sresultatthispoint.Infact,theoperationmighthavenotevenbeenexecutedatthetimethegenericresponsehasreachedtheclient.Clientscanthusnotrelyontheirrequestshavingbeenprocessedsuccessfully.

Theasynchronoustaskqueueontheserverisnotpersisted,meaningnot-yetprocessedtasksfromthequeuewillbelostincaseofacrash.However,theclientwillnotknowwhethertheywereprocessedornot.

Clientsshouldthusnotsendtheextraheaderwhentheyhavestrictdurabilityrequirementsoriftheyrelyonresultofthesentoperationforfurtheractions.

Themaximumnumberofqueuedtasksisdeterminedbythestartupoption-scheduler.maximal-queue-size.Ifmorethanthisnumberoftasksarealreadyqueued,theserverwillrejecttherequestwithanHTTP500error.

Finally,pleasenotethatitisnotpossibletocancelsuchafireandforgetjob,sinceyouwon'tgetanyhandletoidentifyitlateron.Ifyouneedtocancelrequests,useAsyncExecutionandlaterResultRetrievalandHttpJobPutCancelbelow.

AsyncExecutionandlaterResultRetrieval

ByaddingtheHTTPheaderx-arango-async:storetoarequest,clientscaninstructtheArangoDBservertoexecutetheoperationasynchronouslyasabove,butalsostoretheoperationresultinmemoryforalaterretrieval.TheserverwillreturnajobidintheHTTPresponseheaderx-arango-async-id.TheclientcanusethisidinconjunctionwiththeHTTPAPIat/_api/job,whichisdescribedindetailinthismanual.

ClientscanasktheArangoDBserverviatheasyncjobsAPIwhichresultsarereadyforretrieval,andwhicharenot.ClientscanalsousetheasyncjobsAPItoretrievetheoriginalresultsofanalreadyexecutedasyncjobbypassingittheoriginallyreturnedjobid.Theserverwillthenreturnthejobresultasifthejobwasexecutednormally.Furthermore,clientscancancelrunningasyncjobsbytheirjobid,seeHttpJobPutCancel.

AsyncResultHandling

ArangoDBwillkeepallresultsofjobsinitiatedwiththex-arango-async:storeheader.Resultsareremovedfromtheserveronlyifaclientexplicitlyaskstheserverforaspecificresult.

TheasyncjobsAPIalsoprovidesmethodsforgarbagecollectionthatclientscanusetogetridof"old"notfetchedresults.ClientsshouldcallthismethodperiodicallybecauseArangoDBdoesnotartificiallylimitthenumberofnot-yet-fetchedresults.

Itisthusaclientresponsibilitytostoreonlyasmanyresultsasneededandtofetchavailableresultsassoonaspossible,oratleasttocleanupnotfetchedresultsfromtimetotime.

Thejobqueueandtheresultsarekeptinmemoryonlyontheserver,sotheywillbelostincaseofacrash.

Cancelingasynchronousjobs

AsmentionedaboveitispossibletocancelanasynchronouslyrunningjobusingitsjobID.ThisisdonewithaPUTrequestasdescribedinHttpJobPutCancel.

However,afewwordsofexplanationaboutwhathappensbehindthescenesareinorder.Firstly,arunningasyncquerycaninternallybeexecutedbyC++codeorbyJavaScriptcode.ForexampleCRUDoperationsareexecuteddirectlyinC++,whereasAQLqueriesandtransactionsareexecutedbyJavaScriptcode.ThejobcancelationonlyworksforJavaScriptcode,sincethemechanismusedissimplytotriggeranuncatchableexceptionintheJavaScriptthread,whichwillbecaughtontheC++level,whichinturnleadstothecancelationofthejob.Noresultcanberetrievedlater,sincealldataabouttherequestisdiscarded.

Ifyoucancelajobrunningonacoordinatorofacluster(Sharding),thenonlythecoderunningonthecoordinatorisstopped,theremayremaintaskswithintheclusterwhichhavealreadybeendistributedtotheDBserversanditiscurrentlynotpossibletocancelthemaswell.

AsyncExecutionandAuthentication

Ifarequestrequiresauthentication,theauthenticationprocedureisrunbeforequeueing.Therequestwillonlybequeuedifitvalidcredentialsandtheauthenticationsucceeds.Iftherequestdoesnotcontainvalidcredentials,itwillnotbequeuedbutrejectedinstantlyinthesamewayasa"regular",non-queuedrequest.

ManagingAsyncResultsviaHTTP

Returnresultofanasyncjob

fetchesajobresultandremovesitfromthequeue

PUT/_api/job/{job-id}

PathParameters

job-id(required):Theasyncjobid.

Returnstheresultofanasyncjobidentifiedbyjob-id.Iftheasyncjobresultispresentontheserver,theresultwillberemovedfromthelistofresult.Thatmeansthismethodcanbecalledforeachjob-idonce.Themethodwillreturntheoriginaljobresult'sheadersandbody,plustheadditionalHTTPheaderx-arango-async-job-id.Ifthisheaderispresent,thenthejobwasfoundandtheresponsecontainstheoriginaljob'sresult.Iftheheaderisnotpresent,thejobwasnotfoundandtheresponsecontainsstatusinformationfromthejobmanager.

Example:Notprovidingajob-id:

shell>curl-XPUT--dump-http://localhost:8529/_api/job

"error":true,

"errorMessage":"badparameter",

AsyncResultHandling

"code":400,

"errorNum":400

Example:Providingajob-idforanon-existingjob:

shell>curl-XPUT--dump-http://localhost:8529/_api/job/notthere

HTTP/1.1404NotFound

"error":true,

"errorMessage":"notfound",

"code":404,

"errorNum":404

Example:FetchingtheresultofanHTTPGETjob:

shell>curl-XPUT--header'x-arango-async:store'--dump-http://localhost:8529/_api/version

HTTP/1.1202Accepted

x-arango-async-id:151690759883033

content-type:text/plain;charset=utf-8

shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759883033

HTTP/1.1200OK

"server":"arango",

"version":"3.3.3",

"license":"community"

Example:FetchingtheresultofanHTTPPOSTjobthatfailed:

shell>curl-XPUT--header'x-arango-async:store'--data-binary@---dump-http://localhost:8529/_api/collection<<EOF

"name":"thisnameisinvalid"

HTTP/1.1202Accepted

AsyncResultHandling

"error":true,

"errorMessage":"expectedPUT/_api/collection/<collection-name>/<action>",

"code":400,

"errorNum":400

ReturnCodes

204:isreturnedifthejobrequestedviajob-idisstillinthequeueofpending(ornotyetfinished)jobs.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.400:isreturnedifnojob-idwasspecifiedintherequest.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.404:isreturnedifthejobwasnotfoundoralreadydeletedorfetchedfromthejobresultlist.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.

Examples

Notprovidingajob-id:

shell>curl-XPUT--dump-http://localhost:8529/_api/job

showresponsebodyProvidingajob-idforanon-existingjob:

shell>curl-XPUT--dump-http://localhost:8529/_api/job/notthere

HTTP/1.1404NotFound

showresponsebodyFetchingtheresultofanHTTPGETjob:

shell>curl-XPUT--header'x-arango-async:store'--dump-

http://localhost:8529/_api/version

HTTP/1.1202Accepted

HTTP/1.1200OK

showresponsebody

AsyncResultHandling

FetchingtheresultofanHTTPPOSTjobthatfailed:

shell>curl-XPUT--header'x-arango-async:store'--data-binary@---dump-

http://localhost:8529/_api/collection<<EOF

"name":"thisnameisinvalid"

HTTP/1.1202Accepted

showresponsebody

Cancelasyncjob

cancelsanasyncjob

PUT/_api/job/{job-id}/cancel

PathParameters

Cancelsthecurrentlyrunningjobidentifiedbyjob-id.Notethatitstillmighttakesometimetoactuallycanceltherunningasyncjob.

Example:

shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-http://localhost:8529/_api/cursor<<EOF

"query":"FORiIN1..10FORjIN1..10LETx=sleep(1.0)FILTERi==5&&j==5RETURN42"

HTTP/1.1202Accepted

shell>curl--dump-http://localhost:8529/_api/job/pending

HTTP/1.1200OK

"151690759882996"

shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759882996/cancel

HTTP/1.1200OK

AsyncResultHandling

"result":true

HTTP/1.1200OK

"151690759882996"

ReturnCodes

200:cancelhasbeeninitiated.400:isreturnedifnojob-idwasspecifiedintherequest.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.404:isreturnedifthejobwasnotfoundoralreadydeletedorfetchedfromthejobresultlist.Inthiscase,nox-arango-async-idHTTPheaderwillbereturned.

Examples

shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-

http://localhost:8529/_api/cursor<<EOF

"query":"FORiIN1..10FORjIN1..10LETx=sleep(1.0)FILTERi==5&&j==5

RETURN42"

HTTP/1.1202Accepted

HTTP/1.1200OK

"151690759882996"

shell>curl-XPUT--dump-http://localhost:8529/_api/job/151690759882996/cancel

HTTP/1.1200OK

showresponsebody

Deletesasyncjob

deletesanasyncjobresult

DELETE/_api/job/{type}

PathParameters

AsyncResultHandling

type(required):Thetypeofjobstodelete.typecanbe:all:Deletesalljobsresults.Currentlyexecutingorqueuedasyncjobswillnotbestoppedbythiscall.expired:Deletesexpiredresults.Todeterminetheexpirationstatusofaresult,passthestampqueryparameter.stampneedstobeaUNIXtimestamp,andallasyncjobresultscreatedatalowertimestampwillbedeleted.anactualjob-id:Inthiscase,thecallwillremovetheresultofthespecifiedasyncjob.Ifthejobiscurrentlyexecutingorqueued,itwillnotbeaborted.

QueryParameters

stamp(optional):AUNIXtimestampspecifyingtheexpirationthresholdwhentypeisexpired.

Deleteseitheralljobresults,expiredjobresults,ortheresultofaspecificjob.Clientscanusethismethodtoperformaneventualgarbagecollectionofjobresults.

Example:Deletingalljobs:

HTTP/1.1202Accepted

shell>curl-XDELETE--dump-http://localhost:8529/_api/job/all

HTTP/1.1200OK

"result":true

Example:Deletingexpiredjobs:

HTTP/1.1202Accepted

shell>curl--dump-http://localhost:8529/_admin/time

HTTP/1.1200OK

"time":1516907616.271038,

"error":false,

"code":200

shell>curl-XDELETE--dump-http://localhost:8529/_api/job/expired?stamp=1516907616.271038

HTTP/1.1200OK

"result":true

AsyncResultHandling

HTTP/1.1200OK

Example:Deletingtheresultofaspecificjob:

HTTP/1.1202Accepted

shell>curl-XDELETE--dump-http://localhost:8529/_api/job/151690759883019

HTTP/1.1200OK

"result":true

Example:Deletingtheresultofanon-existingjob:

shell>curl-XDELETE--dump-http://localhost:8529/_api/job/AreYouThere

HTTP/1.1404NotFound

"error":true,

"errorMessage":"notfound",

"code":404,

"errorNum":404

ReturnCodes

200:isreturnedifthedeletionoperationwascarriedoutsuccessfully.Thiscodewillalsobereturnedifnoresultsweredeleted.400:isreturnediftypeisnotspecifiedorhasaninvalidvalue.404:isreturnediftypeisajob-idbutnoasyncjobwiththespecifiedidwasfound.

Examples

Deletingalljobs:

HTTP/1.1202Accepted

AsyncResultHandling

shell>curl-XDELETE--dump-http://localhost:8529/_api/job/all

HTTP/1.1200OK

"result":true

Deletingexpiredjobs:

HTTP/1.1202Accepted

shell>curl--dump-http://localhost:8529/_admin/time

HTTP/1.1200OK

showresponsebodyDeletingtheresultofaspecificjob:

HTTP/1.1202Accepted

HTTP/1.1200OK

"result":true

Deletingtheresultofanon-existingjob:

shell>curl-XDELETE--dump-http://localhost:8529/_api/job/AreYouThere

HTTP/1.1404NotFound

AsyncResultHandling

showresponsebody

Returnsasyncjob

Returnsthestatusofaspecificjob

GET/_api/job/{job-id}

PathParameters

Returnstheprocessingstatusofthespecifiedjob.TheprocessingstatuscanbedeterminedbypeekingintotheHTTPresponsecodeoftheresponse.

Example:Queryingthestatusofadonejob:

HTTP/1.1202Accepted

HTTP/1.1200OK

"server":"arango",

"version":"3.3.3",

Example:Queryingthestatusofapendingjob:(thereforewecreatealongrunngingjob...)

shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF

"collections":{

"read":[

"_frontend"

"action":"function(){require('internal').sleep(15.0);}"

HTTP/1.1202Accepted

shell>curl--dump-http://localhost:8529/_api/job/151690759883065

HTTP/1.1204NoContent

AsyncResultHandling

ReturnCodes

200:isreturnedifthejobrequestedviajob-idhasbeenexecutedanditsresultisreadytofetch.204:isreturnedifthejobrequestedviajob-idisstillinthequeueofpending(ornotyetfinished)jobs.404:isreturnedifthejobwasnotfoundoralreadydeletedorfetchedfromthejobresultlist.

Examples

Queryingthestatusofadonejob:

HTTP/1.1202Accepted

HTTP/1.1200OK

showresponsebodyQueryingthestatusofapendingjob:(thereforewecreatealongrunngingjob...)

http://localhost:8529/_api/transaction<<EOF

"collections":{

"read":[

"_frontend"

HTTP/1.1202Accepted

shell>curl--dump-http://localhost:8529/_api/job/151690759883065

Returnslistofasyncjobs

AsyncResultHandling

Returnstheidsofjobresultswithaspecificstatus

GET/_api/job/{type}

PathParameters

type(required):Thetypeofjobstoreturn.Thetypecanbeeitherdoneorpending.Settingthetypetodonewillmakethemethodreturntheidsofalreadycompletedasyncjobsforwhichresultscanbefetched.Settingthetypetopendingwillreturntheidsofnotyetfinishedasyncjobs.

QueryParameters

count(optional):Themaximumnumberofidstoreturnpercall.Ifnotspecified,aserver-definedmaximumvaluewillbeused.

Returnsthelistofidsofasyncjobswithaspecificstatus(eitherdoneorpending).Thelistcanbeusedbytheclienttogetanoverviewofthejobsystemstatusandtoretrievecompletedjobresultslater.

Example:Fetchingthelistofdonejobs:

HTTP/1.1202Accepted

shell>curl--dump-http://localhost:8529/_api/job/done

HTTP/1.1200OK

"151690759883043"

Example:Fetchingthelistofpendingjobs:

HTTP/1.1202Accepted

HTTP/1.1200OK

Example:Queryingthestatusofapendingjob:(wecreateasleepjobtherefore...)

shell>curl-XPOST--header'x-arango-async:store'--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF

"collections":{

AsyncResultHandling

"read":[

"_frontend"

HTTP/1.1202Accepted

HTTP/1.1200OK

"151690759883053"

HTTP/1.1200OK

"result":true

ReturnCodes

200:isreturnedifthelistcanbecompiledsuccessfully.Note:thelistmightbeempty.400:isreturnediftypeisnotspecifiedorhasaninvalidvalue.

Examples

Fetchingthelistofdonejobs:

HTTP/1.1202Accepted

shell>curl--dump-http://localhost:8529/_api/job/done

HTTP/1.1200OK

"151690759883043"

Fetchingthelistofpendingjobs:

HTTP/1.1202Accepted

AsyncResultHandling

HTTP/1.1200OK

Queryingthestatusofapendingjob:(wecreateasleepjobtherefore...)

http://localhost:8529/_api/transaction<<EOF

"collections":{

"read":[

"_frontend"

HTTP/1.1202Accepted

HTTP/1.1200OK

"151690759883053"

HTTP/1.1200OK

"result":true

AsyncResultHandling

HTTPInterfaceforBulkImportsArangoDBprovidesanHTTPinterfacetoimportmultipledocumentsatonceintoacollection.Thisisknownasabulkimport.

ThedatauploadedmustbeprovidedinJSONformat.Therearetwomechanismstoimportthedata:

self-containedJSONdocuments:inthiscase,eachdocumentcontainsallattributenamesandvalues.Attributenamesmaybecompletelydifferentamongthedocumentsuploadedattributenamesplusdocumentdata:inthiscase,thefirstarraymustcontaintheattributenamesofthedocumentsthatfollow.Thefollowingarrayscontainingonlytheattributevalues.Attributevalueswillbemappedtotheattributenamesbypositions.

Theendpointaddressis/_api/importforbothinputmechanisms.DatamustbesenttothisURLusinganHTTPPOSTrequest.ThedatatoimportmustbecontainedinthebodyofthePOSTrequest.

Thecollectionqueryparametermustbeusedtospecifythetargetcollectionfortheimport.Importingdataintoanon-existingcollectionwillproduceanerror.

ThewaitForSyncqueryparametercanbesettotruetomaketheimportonlyreturnifalldocumentshavebeensyncedtodisk.

Thecompletequeryparametercanbesettotruetomaketheentireimportfailifanyoftheuploadeddocumentsisinvalidandcannotbeimported.Inthiscase,nodocumentswillbeimportedbytheimportrun,evenifafailurehappensattheendoftheimport.

Ifcompletehasavalueotherthantrue,validdocumentswillbeimportedwhileinvaliddocumentswillberejected,meaningonlysomeoftheuploadeddocumentsmighthavebeenimported.

ThedetailsqueryparametercanbesettotruetomaketheimportAPIreturndetailsaboutdocumentsthatcouldnotbeimported.Ifdetailsistrue,thentheresultwillalsocontainadetailsattributewhichisanarrayofdetailederrormessages.Ifthedetailsissettofalseoromitted,nodetailswillbereturned.

importsdocumentvalues

importsdocumentsfromJSON-encodedlists

POST/_api/import#document

ThebodymustconsistofJSON-encodedarraysofattributevalues,withonelineperdocument.ThefirstrowoftherequestmustbeaJSON-encodedarrayofattributenames.Theseattributenamesareusedforthedatainthesubsequentlines.

QueryParameters

collection(required):Thecollectionname.fromPrefix(optional):Anoptionalprefixforthevaluesin_fromattributes.Ifspecified,thevalueisautomaticallyprependedtoeach_frominputvalue.Thisallowsspecifyingjustthekeysfor_from.toPrefix(optional):Anoptionalprefixforthevaluesin_toattributes.Ifspecified,thevalueisautomaticallyprependedtoeach_toinputvalue.Thisallowsspecifyingjustthekeysfor_to.overwrite(optional):Ifthisparameterhasavalueoftrueoryes,thenalldatainthecollectionwillberemovedpriortotheimport.Notethatanyexistingindexdefinitionswillbepreseved.waitForSync(optional):Waituntildocumentshavebeensyncedtodiskbeforereturning.onDuplicate(optional):Controlswhatactioniscarriedoutincaseofauniquekeyconstraintviolation.Possiblevaluesare:error:thiswillnotimportthecurrentdocumentbecauseoftheuniquekeyconstraintviolation.Thisisthedefaultsetting.update:thiswillupdateanexistingdocumentinthedatabasewiththedataspecifiedintherequest.Attributesoftheexistingdocumentthatarenotpresentintherequestwillbepreseved.replace:thiswillreplaceanexistingdocumentinthedatabasewiththedataspecifiedintherequest.ignore:thiswillnotupdateanexistingdocumentandsimplyignoretheerrorcausedbytheuniquekeyconstraintviolation.Notethatupdate,replaceandignorewillonlyworkwhentheimportdocumentintherequestcontainsthe_keyattribute.updateandreplacemayalsofailbecauseofsecondaryuniquekeyconstraintviolations.complete(optional):Ifsettotrueoryes,itwillmakethewholeimportfailifanyerroroccurs.Otherwisetheimportwillcontinueevenifsomedocumentscannotbeimported.details(optional):Ifsettotrueoryes,theresultwillincludeanattributedetailswithdetailsaboutdocumentsthatcouldnot

BulkImport/Export

beimported.

NOTESwaggerexampleswon'tworkduetotheanchor.

Createsdocumentsinthecollectionidentifiedbycollection-name.ThefirstlineoftherequestbodymustcontainaJSON-encodedarrayofattributenames.AllfollowinglinesintherequestbodymustcontainJSON-encodedarraysofattributevalues.Eachlineisinterpretedasaseparatedocument,andthevaluesspecifiedwillbemappedtothearrayofattributenamesspecifiedinthefirstheaderline.

created:numberofdocumentsimported.

errors:numberofdocumentsthatwerenotimportedduetoanerror.

empty:numberofemptylinesfoundintheinput(willonlycontainavaluegreaterzerofortypesdocumentsorauto).

updated:numberofupdated/replaceddocuments(incaseonDuplicatewassettoeitherupdateorreplace).

ignored:numberoffailedbutignoredinsertoperations(incaseonDuplicatewassettoignore).

details:ifqueryparameterdetailsissettotrue,theresultwillcontainadetailsattributewhichisanarraywithmoredetailedinformationaboutwhichdocumentscouldnotbeinserted.

Example:Importingtwodocuments,withattributes_key,value1andvalue2each.Onelineintheimportdataisempty

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products<<EOF

["_key","value1","value2"]

["abc",25,"test"]

["foo","bar","baz"]

HTTP/1.1201Created

"error":false,

"created":2,

"errors":0,

"empty":1,

"updated":0,

"ignored":0

Example:Importingintoanedgecollection,withattributes_from,_toandname

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=links<<EOF

["_from","_to","name"]

["products/123","products/234","somename"]

["products/332","products/abc","othername"]

HTTP/1.1201Created

"error":false,

"created":2,

"errors":0,

"empty":0,

BulkImport/Export

"updated":0,

"ignored":0

Example:Importingintoanedgecollection,omitting_fromor_to

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=links&details=true<<EOF

["name"]

["somename"]

["othername"]

HTTP/1.1201Created

"error":false,

"created":0,

"errors":2,

"empty":0,

"updated":0,

"ignored":0,

"details":[

"atposition1:missing'_from'or'_to'attribute,offendingdocument:{\"name\":\"somename\"}",

"atposition2:missing'_from'or'_to'attribute,offendingdocument:{\"name\":\"othername\"}"

Example:Violatingauniqueconstraint,butallowpartialimports

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&details=true<<EOF

["abc",25,"test"]

["abc","bar","baz"]

HTTP/1.1201Created

"error":false,

"created":1,

"errors":1,

"empty":0,

"updated":0,

"ignored":0,

"details":[

"atposition1:creatingdocumentfailedwitherror'uniqueconstraintviolated',offendingdocument:{\"_key\":\"abc\",\"v

alue1\":\"bar\",\"value2\":\"baz\"}"

Example:Violatingauniqueconstraint,notallowingpartialimports

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&complete=true<<EOF

BulkImport/Export

["abc",25,"test"]

["abc","bar","baz"]

HTTP/1.1409Conflict

"error":true,

"errorMessage":"uniqueconstraintviolated",

"code":409,

"errorNum":1210

Example:Usinganon-existingcollection

["abc",25,"test"]

["foo","bar","baz"]

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":1203

Example:Usingamalformedbody

{"_key":"foo","value1":"bar"}

"error":true,

"errorMessage":"noJSONarrayfoundinsecondline",

"code":400,

"errorNum":400

ReturnCodes

201:isreturnedifalldocumentscouldbeimportedsuccessfully.400:isreturnediftypecontainsaninvalidvalue,nocollectionisspecified,thedocumentsareincorrectlyencoded,ortherequestismalformed.404:isreturnedifcollectionorthe_fromor_toattributesofanimportededgerefertoanunknowncollection.409:isreturnediftheimportwouldtriggerauniquekeyviolationandcompleteissettotrue.500:isreturnediftheservercannotauto-generateadocumentkey(outofkeyserror)foradocumentwithnouser-definedkey.

Examples

BulkImport/Export

Importingtwodocuments,withattributes_key,value1andvalue2each.Onelineintheimportdataisempty

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?

collection=products<<EOF

["abc",25,"test"]

["foo","bar","baz"]

HTTP/1.1201Created

showresponsebodyImportingintoanedgecollection,withattributes_from,_toandname

collection=links<<EOF

["_from","_to","name"]

["products/123","products/234","somename"]

["products/332","products/abc","othername"]

HTTP/1.1201Created

showresponsebodyImportingintoanedgecollection,omitting_fromor_to

collection=links&details=true<<EOF

["name"]

["somename"]

["othername"]

HTTP/1.1201Created

showresponsebodyViolatingauniqueconstraint,butallowpartialimports

collection=products&details=true<<EOF

["abc",25,"test"]

["abc","bar","baz"]

BulkImport/Export

HTTP/1.1201Created

showresponsebodyViolatingauniqueconstraint,notallowingpartialimports

collection=products&complete=true<<EOF

["abc",25,"test"]

["abc","bar","baz"]

HTTP/1.1409Conflict

showresponsebodyUsinganon-existingcollection

["abc",25,"test"]

["foo","bar","baz"]

HTTP/1.1404NotFound

showresponsebodyUsingamalformedbody

{"_key":"foo","value1":"bar"}

showresponsebody

importsdocumentsfromJSON

POST/_api/import#json

BulkImport/Export

ThebodymusteitherbeaJSON-encodedarrayofobjectsorastringwithmultipleJSONobjectsseparatedbynewlines.

QueryParameters

type(required):Determineshowthebodyoftherequestwillbeinterpreted.typecanhavethefollowingvalues:documents:whenthistypeisused,eachlineintherequestbodyisexpectedtobeanindividualJSON-encodeddocument.MultipleJSONobjectsintherequestbodyneedtobeseparatedbynewlines.list:whenthistypeisused,therequestbodymustcontainasingleJSON-encodedarrayofindividualobjectstoimport.auto:ifset,thiswillautomaticallydeterminethebodytype(eitherdocumentsorlist).collection(required):Thecollectionname.fromPrefix(optional):Anoptionalprefixforthevaluesin_fromattributes.Ifspecified,thevalueisautomaticallyprependedtoeach_frominputvalue.Thisallowsspecifyingjustthekeysfor_from.toPrefix(optional):Anoptionalprefixforthevaluesin_toattributes.Ifspecified,thevalueisautomaticallyprependedtoeach_toinputvalue.Thisallowsspecifyingjustthekeysfor_to.overwrite(optional):Ifthisparameterhasavalueoftrueoryes,thenalldatainthecollectionwillberemovedpriortotheimport.Notethatanyexistingindexdefinitionswillbepreseved.waitForSync(optional):Waituntildocumentshavebeensyncedtodiskbeforereturning.onDuplicate(optional):Controlswhatactioniscarriedoutincaseofauniquekeyconstraintviolation.Possiblevaluesare:error:thiswillnotimportthecurrentdocumentbecauseoftheuniquekeyconstraintviolation.Thisisthedefaultsetting.update:thiswillupdateanexistingdocumentinthedatabasewiththedataspecifiedintherequest.Attributesoftheexistingdocumentthatarenotpresentintherequestwillbepreseved.replace:thiswillreplaceanexistingdocumentinthedatabasewiththedataspecifiedintherequest.ignore:thiswillnotupdateanexistingdocumentandsimplyignoretheerrorcausedbyauniquekeyconstraintviolation.Notethatthatupdate,replaceandignorewillonlyworkwhentheimportdocumentintherequestcontainsthe_keyattribute.updateandreplacemayalsofailbecauseofsecondaryuniquekeyconstraintviolations.complete(optional):Ifsettotrueoryes,itwillmakethewholeimportfailifanyerroroccurs.Otherwisetheimportwillcontinueevenifsomedocumentscannotbeimported.details(optional):Ifsettotrueoryes,theresultwillincludeanattributedetailswithdetailsaboutdocumentsthatcouldnotbeimported.

Createsdocumentsinthecollectionidentifiedbycollection-name.TheJSONrepresentationsofthedocumentsmustbepassedasthebodyofthePOSTrequest.Therequestbodycaneitherconsistofmultiplelines,witheachlinebeingasinglestand-aloneJSONobject,orasingeJSONarraywithsub-objects.

created:numberofdocumentsimported.

errors:numberofdocumentsthatwerenotimportedduetoanerror.

empty:numberofemptylinesfoundintheinput(willonlycontainavaluegreaterzerofortypesdocumentsorauto).

updated:numberofupdated/replaceddocuments(incaseonDuplicatewassettoeitherupdateorreplace).

ignored:numberoffailedbutignoredinsertoperations(incaseonDuplicatewassettoignore).

details:ifqueryparameterdetailsissettotrue,theresultwillcontainadetailsattributewhichisanarraywithmoredetailedinformationaboutwhichdocumentscouldnotbeinserted.

Example:ImportingdocumentswithheterogenousattributesfromaJSONarray

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=list<<EOF

"_key":"abc",

"value1":25,

BulkImport/Export

"value2":"test",

"allowed":true

"_key":"foo",

"name":"baz"

"name":{

"detailed":"detailedname",

"short":"shortname"

HTTP/1.1201Created

"error":false,

"created":3,

"errors":0,

"empty":0,

"updated":0,

"ignored":0

Example:ImportingdocumentsfromindividualJSONlines

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=documents<<EOF

{"_key":"abc","value1":25,"value2":"test","allowed":true}

{"_key":"foo","name":"baz"}

{"name":{"detailed":"detailedname","short":"shortname"}}

HTTP/1.1201Created

"error":false,

"created":3,

"errors":0,

"empty":1,

"updated":0,

"ignored":0

Example:Usingtheautotypedetection

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=auto<<EOF

"_key":"abc",

"value1":25,

"value2":"test",

"allowed":true

"_key":"foo",

BulkImport/Export

"name":"baz"

"name":{

"short":"shortname"

HTTP/1.1201Created

"error":false,

"created":3,

"errors":0,

"empty":0,

"updated":0,

"ignored":0

Example:Importingintoanedgecollection,withattributes_from,_toandname

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=links&type=documents<<EOF

{"_from":"products/123","_to":"products/234"}

{"_from":"products/332","_to":"products/abc","name":"othername"}

HTTP/1.1201Created

"error":false,

"created":2,

"errors":0,

"empty":0,

"updated":0,

"ignored":0

Example:Importingintoanedgecollection,omitting_fromor_to

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=links&type=list&details=true<<EOF

"name":"somename"

HTTP/1.1201Created

"error":false,

"created":0,

"errors":1,

"empty":0,

"updated":0,

BulkImport/Export

"ignored":0,

"details":[

"atposition1:missing'_from'or'_to'attribute,offendingdocument:{\"name\":\"somename\"}"

Example:Violatingauniqueconstraint,butallowpartialimports

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=documents&details=true

{"_key":"abc","value1":25,"value2":"test"}

{"_key":"abc","value1":"bar","value2":"baz"}

HTTP/1.1201Created

"error":false,

"created":1,

"errors":1,

"empty":0,

"updated":0,

"ignored":0,

"details":[

"atposition1:creatingdocumentfailedwitherror'uniqueconstraintviolated',offendingdocument:{\"_key\":\"abc\",\"v

alue1\":\"bar\",\"value2\":\"baz\"}"

Example:Violatingauniqueconstraint,notallowingpartialimports

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=documents&complete=tru

e<<EOF

HTTP/1.1409Conflict

"error":true,

"errorMessage":"uniqueconstraintviolated",

"code":409,

"errorNum":1210

Example:Usinganon-existingcollection

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=documents<<EOF

{"name":"test"}

HTTP/1.1404NotFound

BulkImport/Export

"error":true,

"code":404,

"errorNum":1203

Example:Usingamalformedbody

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/import?collection=products&type=list<<EOF

"error":true,

"errorMessage":"expectingaJSONarrayintherequest",

"code":400,

"errorNum":400

ReturnCodes

201:isreturnedifalldocumentscouldbeimportedsuccessfully.400:isreturnediftypecontainsaninvalidvalue,nocollectionisspecified,thedocumentsareincorrectlyencoded,ortherequestismalformed.404:isreturnedifcollectionorthe_fromor_toattributesofanimportededgerefertoanunknowncollection.409:isreturnediftheimportwouldtriggerauniquekeyviolationandcompleteissettotrue.500:isreturnediftheservercannotauto-generateadocumentkey(outofkeyserror)foradocumentwithnouser-definedkey.

Examples

ImportingdocumentswithheterogenousattributesfromaJSONarray

collection=products&type=list<<EOF

"_key":"abc",

"value1":25,

"value2":"test",

"allowed":true

"_key":"foo",

"name":"baz"

"name":{

"short":"shortname"

BulkImport/Export

HTTP/1.1201Created

showresponsebodyImportingdocumentsfromindividualJSONlines

collection=products&type=documents<<EOF

{"_key":"abc","value1":25,"value2":"test","allowed":true}

{"_key":"foo","name":"baz"}

{"name":{"detailed":"detailedname","short":"shortname"}}

HTTP/1.1201Created

showresponsebodyUsingtheautotypedetection

collection=products&type=auto<<EOF

"_key":"abc",

"value1":25,

"value2":"test",

"allowed":true

"_key":"foo",

"name":"baz"

"name":{

"short":"shortname"

HTTP/1.1201Created

showresponsebody

BulkImport/Export

Importingintoanedgecollection,withattributes_from,_toandname

collection=links&type=documents<<EOF

{"_from":"products/123","_to":"products/234"}

{"_from":"products/332","_to":"products/abc","name":"othername"}

HTTP/1.1201Created

showresponsebodyImportingintoanedgecollection,omitting_fromor_to

collection=links&type=list&details=true<<EOF

"name":"somename"

HTTP/1.1201Created

showresponsebodyViolatingauniqueconstraint,butallowpartialimports

collection=products&type=documents&details=true<<EOF

HTTP/1.1201Created

showresponsebodyViolatingauniqueconstraint,notallowingpartialimports

collection=products&type=documents&complete=true<<EOF

HTTP/1.1409Conflict

BulkImport/Export

showresponsebodyUsinganon-existingcollection

collection=products&type=documents<<EOF

{"name":"test"}

HTTP/1.1404NotFound

showresponsebodyUsingamalformedbody

collection=products&type=list<<EOF

showresponsebody

BulkImport/Export

ImportingSelf-ContainedJSONDocumentsThisimportmethodallowsuploadingself-containedJSONdocuments.ThedocumentsmustbeuploadedinthebodyoftheHTTPPOSTrequest.Eachlineofthebodywillbeinterpretedasonestand-alonedocument.Emptylinesinthebodyareallowedbutwillbeskipped.Usingthisformat,thedocumentsareimportedline-wise.

Exampleinputdata:{"_key":"key1",...}{"_key":"key2",...}...

Tousethismethod,thetypequeryparametershouldbesettodocuments.

Itisalsopossibletouploadself-containedJSONdocumentsthatareembeddedintoaJSONarray.Eachelementfromthearraywillbetreatedasadocumentandbeimported.

Exampleinputdataforthiscase:

{"_key":"key1",...},

{"_key":"key2",...},

Thisformatdoesnotrequireeachdocumenttobeonaseparateline,andanywhitespaceintheJSONdataisallowed.ItcanbeusedtoimportaJSON-formattedresultarray(e.g.fromarangosh)backintoArangoDB.UsingthisformatrequiresArangoDBtoparsethecompletearrayandkeepitinmemoryforthedurationoftheimport.Thismightbemoreresource-intensivethantheline-wiseprocessing.

Tousethismethod,thetypequeryparametershouldbesettoarray.

Settingthetypequeryparametertoautowillmaketheserverauto-detectwhetherthedataareline-wiseJSONdocuments(type=documents)oraJSONarray(type=array).

Examples

curl--data-binary@--XPOST--dump-"http://localhost:8529/_api/import?type=documents&collection=test"

{"name":"test","gender":"male","age":39}

{"type":"bird","name":"robin"}

HTTP/1.1201Created

Server:ArangoDB

{"error":false,"created":2,"empty":0,"errors":0}

TheserverwillrespondwithanHTTP201ifeverythingwentwell.Thenumberofdocumentsimportedwillbereturnedinthecreatedattributeoftheresponse.Ifanydocumentswereskippedorincorrectlyformatted,thiswillbereturnedintheerrorsattribute.Therewillalsobeanattributeemptyintheresponse,whichwillcontainavalueof0.

Ifthedetailsparameterwassettotrueintherequest,theresponsewillalsocontainanattributedetailswhichisanarrayofdetailsabouterrorsthatoccurredontheserversideduringtheimport.Thisarraymightbeemptyifnoerrorsoccurred.

JSONDocuments

ImportingHeadersandValuesWhenusingthistypeofimport,theattributenamesofthedocumentstobeimportedarespecifiedseparatefromtheactualdocumentvaluedata.ThefirstlineoftheHTTPPOSTrequestbodymustbeaJSONarraycontainingtheattributenamesforthedocumentsthatfollow.Thefollowinglinesareinterpretedasthedocumentdata.EachdocumentmustbeaJSONarrayofvalues.Noattributenamesareneededorallowedinthisdatasection.

Examples

curl--data-binary@--XPOST--dump-"http://localhost:8529/_api/import?collection=test"

["firstName","lastName","age","gender"]

["Joe","Public",42,"male"]

["Jane","Doe",31,"female"]

HTTP/1.1201Created

Server:ArangoDB

{"error":false,"created":2,"empty":0,"errors":0}

TheserverwillagainrespondwithanHTTP201ifeverythingwentwell.Thenumberofdocumentsimportedwillbereturnedinthecreatedattributeoftheresponse.Ifanydocumentswereskippedorincorrectlyformatted,thiswillbereturnedintheerrorsattribute.Thenumberofemptylinesintheinputfilewillbereturnedintheemptyattribute.

Ifthedetailsparameterwassettotrueintherequest,theresponsewillalsocontainanattributedetailswhichisanarrayofdetailsabouterrorsthatoccurredontheserversideduringtheimport.Thisarraymightbeemptyifnoerrorsoccurred.

ImportingintoEdgeCollections

Pleasenotethatwhenimportingdocumentsintoanedgecollection,itismandatorythatallimporteddocumentscontainthe_fromand_toattributes,andthatthesecontainreferencestoexistingcollections.

Headers&Values

HTTPInterfaceforBatchRequestsClientsnormallysendindividualoperationstoArangoDBinindividualHTTPrequests.Thisisstraightforwardandsimple,buthasthedisadvantagethatthenetworkoverheadcanbesignificantifmanysmallrequestsareissuedinarow.

Tomitigatethisproblem,ArangoDBoffersabatchrequestAPIthatclientscanusetosendmultipleoperationsinonebatchtoArangoDB.ThismethodisespeciallyusefulwhentheclienthastosendmanyHTTPrequestswithasmallbody/payloadandtheindividualrequestresultsdonotdependoneachother.

ClientscanuseArangoDB'sbatchAPIbyissuingamultipartHTTPPOSTrequesttotheURL/_api/batchhandler.ThehandlerwillaccepttherequestiftheContent-typeismultipart/form-dataandaboundarystringisspecified.ArangoDBwillthendecomposethebatchrequestintoitsindividualpartsusingthisboundary.Thisalsomeansthattheboundarystringitselfmustnotbecontainedinanyoftheparts.WhenArangoDBhassplitthemultipartrequestintoitsindividualparts,itwillprocessallpartssequentiallyasifitwereastandalonerequest.Whenallpartsareprocessed,ArangoDBwillgenerateamultipartHTTPresponsethatcontainsonepartforeachpartoperationresult.Forexample,ifyousendamultipartrequestwith5parts,ArangoDBwillsendbackamultipartresponsewith5partsaswell.

Theserverexpectseachpartmessagetostartwithexactlythefollowing"header":

Content-type:application/x-arango-batchpart

YoucanoptionallyspecifyaContent-Id"header"touniquelyidentifyeachpartmessage.TheserverwillreturntheContent-Idinitsresponseifitisspecified.Otherwise,theserverwillnotsendaContent-Id"header"back.TheserverwillnotvalidatetheuniquenessoftheContent-Id.AfterthemandatoryContent-typeandtheoptionalContent-Idheader,twoWindowslinebreaks(i.e.\r\n\r\n)mustfollow.Anydeviationofthisstructuremightleadtothepartbeingrejectedorincorrectlyinterpreted.Thepartrequestpayload,formattedasaregularHTTPrequest,mustfollowthetwoWindowslinebreaksliteraldirectly.

NotethattheliteralContent-type:application/x-arango-batchparttechnicallyistheheaderoftheMIMEpart,andtheHTTPrequest(includingitsheaders)isthebodypartoftheMIMEpart.

AnactualpartrequestshouldstartwiththeHTTPmethod,thecalledURL,andtheHTTPprotocolversionasusual,followedbyarbitraryHTTPheaders.Itsbodyshouldfollowaftertheusual\r\n\r\nliteral.PartrequestsarethereforeregularHTTPrequests,onlyembeddedinsideamultipartmessage.

Thefollowingexamplewillsendabatchwith3individualdocumentcreationoperations.TheboundaryusedinthisexampleisXXXsubpartXXX.

Examples

>curl-XPOST--data-binary@---header"Content-type:multipart/form-data;boundary=XXXsubpartXXX"http://localhost:8529/_api

/batch

--XXXsubpartXXX

Content-Id:1

POST/_api/document?collection=xyzHTTP/1.1

{"a":1,"b":2,"c":3}

--XXXsubpartXXX

Content-Id:2

{"a":1,"b":2,"c":3,"d":4}

--XXXsubpartXXX

Content-Id:3

{"a":1,"b":2,"c":3,"d":4,"e":5}

--XXXsubpartXXX--

BatchRequests

Theserverwillthenrespondwithonemultipartmessage,containingtheoverallstatusandtheindividualresultsforthepartoperations.Theoverallstatusshouldbe200excepttherewasanerrorwhileinspectingandprocessingthemultipartmessage.Theoverallstatusthereforedoesnotindicatethesuccessofeachpartoperation,butonlyindicateswhetherthemultipartmessagecouldbehandledsuccessfully.

Eachpartoperationwillreturnitsownstatusvalue.AsthepartoperationresultsareregularHTTPresponses(justincludedinonemultipartresponse),thepartoperationstatusisreturnedasaHTTPstatuscode.Thestatuscodesofthepartoperationsareexactlythesameasifyoucalledtheindividualoperationsstandalone.EachpartoperationmightalsoreturnarbitraryHTTPheadersandabody/payload:

Examples

HTTP/1.1200OK

Content-type:multipart/form-data;boundary=XXXsubpartXXX

Content-length:1055

--XXXsubpartXXX

Content-Id:1

HTTP/1.1202Accepted

Etag:"9514299"

Content-length:53

{"error":false,"_id":"xyz/9514299","_key":"9514299","_rev":"9514299"}

--XXXsubpartXXX

Content-Id:2

HTTP/1.1202Accepted

Etag:"9579835"

Content-length:53

--XXXsubpartXXX

Content-Id:3

HTTP/1.1202Accepted

Etag:"9645371"

Content-length:53

--XXXsubpartXXX--

Intheaboveexample,theserverreturnedanoverallstatuscodeof200,andeachpartresponsecontainsitsownstatusvalue(202intheexample):

WhenconstructingthemultipartHTTPresponse,theserverwillusethesameboundarythattheclientsupplied.Ifanyofthepartresponseshasastatuscodeof400orgreater,theserverwillalsoreturnanHTTPheaderx-arango-errorscontainingtheoverallnumberofpartrequeststhatproducederrors:

Examples

>curl-XPOST--data-binary@---header"Content-type:multipart/form-data;boundary=XXXsubpartXXX"http://localhost:8529/_api

/batch

--XXXsubpartXXX

POST/_api/document?collection=nonexisting

{"a":1,"b":2,"c":3}

--XXXsubpartXXX

POST/_api/document?collection=xyz

BatchRequests

{"a":1,"b":2,"c":3,"d":4}

--XXXsubpartXXX--

Inthisexample,theoverallresponsecodeis200,butassomeofthepartrequestfailed(withstatuscode404),thex-arango-errorsheaderoftheoverallresponseis1:

Examples

HTTP/1.1200OK

x-arango-errors:1

Content-type:multipart/form-data;boundary=XXXsubpartXXX

Content-length:711

--XXXsubpartXXX

HTTP/1.1404NotFound

Content-length:111

{"error":true,"code":404,"errorNum":1203,"errorMessage":"collection\/_api\/collection\/nonexistingnotfound"}

--XXXsubpartXXX

HTTP/1.1202Accepted

Etag:"9841979"

Content-length:53

--XXXsubpartXXX--

PleasenotethatthedatabaseusedforallpartoperationsofabatchrequestisdeterminedbyscanningtheoriginalURL(theURLthatcontains/_api/batch).Itisnotpossibletooverridethedatabasenameinpartoperationsofabatch.Whendoingso,anyotherdatabasenameusedinabatchpartwillbeignored.

executesabatchrequest

POST/_api/batch

Themultipartbatchrequest,consistingoftheenvelopeandtheindividualbatchparts.

Executesabatchrequest.AbatchrequestcancontainanynumberofotherrequeststhatcanbesenttoArangoDBinisolation.Thebenefitofusingbatchrequestsisthatbatchingrequestsrequireslessclient/serverroundtripsthanwhensendingisolatedrequests.

Allpartsofabatchrequestareexecutedseriallyontheserver.Theserverwillreturntheresultsofallpartsinasingleresponsewhenallpartsarefinished.

Technically,abatchrequestisamultipartHTTPrequest,withcontent-typemultipart/form-data.Abatchrequestconsistsofanenvelopeandtheindividualbatchpartactions.Batchpartactionsare"regular"HTTPrequests,includingfullheaderandanoptionalbody.Multiplebatchpartsareseparatedbyaboundaryidentifier.Theboundaryidentifierisdeclaredinthebatchenvelope.TheMIMEcontent-typeforeachindividualbatchpartmustbeapplication/x-arango-batchpart.

Pleasenotethatwhenconstructingtheindividualbatchparts,youmustuseCRLF(\\)asthelineterminatorasinregularHTTPmessages.

TheresponsesentbytheserverwillbeanHTTP200response,withanoptionalerrorsummaryheaderx-arango-errors.ThisheadercontainsthenumberofbatchpartoperationsthatfailedwithanHTTPerrorcodeofatleast400.Thisheaderisonlypresentintheresponseifthenumberoferrorsisgreaterthanzero.

Theresponsesentbytheserverisamultipartresponse,too.ItcontainstheindividualHTTPresponsesforallbatchparts,includingthefullHTTPresultheader(withstatuscodeandotherpotentialheaders)andanoptionalresultbody.Theindividualbatchpartsintheresultareseperatedusingthesameboundaryvalueasspecifiedintherequest.

BatchRequests

Theorderofbatchpartsintheresponsewillbethesameasintheoriginalclientrequest.ClientcanadditionallyusetheContent-IdMIMEheaderinabatchparttodefineanindividualidforeachbatchpart.Theserverwillreturnthisidisthebatchpartresponses,too.

Example:Sendingabatchrequestwithfivebatchparts:

GET/_api/version

DELETE/_api/collection/products

POST/_api/collection/products

GET/_api/collection/products/figures

DELETE/_api/collection/products

Theboundary(SomeBoundaryValue)ispassedtotheserverintheHTTPContent-TypeHTTPheader.Pleasenotethereplyisnotdisplayedallaccurate.

shell>curl-XPOST--header'Content-Type:multipart/form-data;boundary=SomeBoundaryValue'--data-binary@---dump-http://l

ocalhost:8529/_api/batch<<EOF

--SomeBoundaryValue

Content-Type:application/x-arango-batchpart

Content-Id:myId1

GET/_api/versionHTTP/1.1

--SomeBoundaryValue

Content-Id:myId2

DELETE/_api/collection/productsHTTP/1.1

--SomeBoundaryValue

Content-Id:someId

POST/_api/collection/productsHTTP/1.1

{"name":"products"}

--SomeBoundaryValue

Content-Id:nextId

GET/_api/collection/products/figuresHTTP/1.1

--SomeBoundaryValue

Content-Id:otherId

--SomeBoundaryValue--

HTTP/1.1200OK

content-type:multipart/form-data;boundary=SomeBoundaryValue

x-arango-errors:1

"--SomeBoundaryValue

Content-Id:myId1

HTTP/1.1200OK

Server:

Connection:

Content-Length:59

BatchRequests

{\"server\":\"arango\",\"version\":\"3.3.3\",\"license\":\"community\"}

--SomeBoundaryValue

Content-Id:myId2

HTTP/1.1404NotFound

Server:

Connection:

Content-Length:79

{\"error\":true,\"errorMessage\":\"collectionnotfound\",\"code\":404,\"errorNum\":1203}

--SomeBoundaryValue

Content-Id:someId

HTTP/1.1200OK

Server:

Connection:

Content-Length:324

{\"code\":200,\"error\":false,\"status\":3,\"statusString\":\"loaded\",\"name\":\"products\",\"keyOptions\":{\"type\":\"traditi

onal\",\"allowUserKeys\":true,\"lastValue\":0},\"type\":2,\"indexBuckets\":8,\"globallyUniqueId\":\"h68719E5AC6E7/9990\",\"doCo

mpact\":true,\"waitForSync\":false,\"id\":\"9990\",\"isSystem\":false,\"journalSize\":33554432,\"isVolatile\":false}

--SomeBoundaryValue

Content-Id:nextId

HTTP/1.1200OK

Server:

Location:/_api/collection/products/figures

Connection:

Content-Length:831

{\"code\":200,\"error\":false,\"statusString\":\"loaded\",\"name\":\"products\",\"keyOptions\":{\"type\":\"traditional\",\"allo

wUserKeys\":true,\"lastValue\":0},\"journalSize\":33554432,\"isVolatile\":false,\"isSystem\":false,\"status\":3,\"count\":0,\"f

igures\":{\"indexes\":{\"count\":1,\"size\":32128},\"documentReferences\":0,\"waitingFor\":\"-\",\"alive\":{\"count\":0,\"size\

":0},\"dead\":{\"count\":0,\"size\":0,\"deletion\":0},\"compactionStatus\":{\"message\":\"compactionnotyetstarted\",\"time\"

:\"2018-01-25T19:13:37Z\",\"count\":0,\"filesCombined\":0,\"bytesRead\":0,\"bytesWritten\":0},\"datafiles\":{\"count\":0,\"file

Size\":0},\"journals\":{\"count\":0,\"fileSize\":0},\"compactors\":{\"count\":0,\"fileSize\":0},\"revisions\":{\"count\":0,\"si

ze\":48192},\"lastTick\":0,\"uncollectedLogfileEntries\":0},\"doCompact\":true,\"globallyUniqueId\":\"h68719E5AC6E7/9990\",\"ty

pe\":2,\"indexBuckets\":8,\"waitForSync\":false,\"id\":\"9990\"}

--SomeBoundaryValue

Content-Id:otherId

HTTP/1.1200OK

Server:

Connection:

Content-Length:38

{\"code\":200,\"error\":false,\"id\":\"9990\"}

--SomeBoundaryValue--"

Example:Sendingabatchrequest,settingtheboundaryimplicitly(theserverwillinthiscasetrytofindtheboundaryatthebeginningoftherequestbody).

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/batch<<EOF

--SomeBoundaryValue

DELETE/_api/collection/notexisting1HTTP/1.1

--SomeBoundaryValue

DELETE_api/collection/notexisting2HTTP/1.1

BatchRequests

HTTP/1.1200OK

content-type:

x-arango-errors:2

"--SomeBoundaryValue

HTTP/1.1404NotFound

Server:

Connection:

Content-Length:79

{\"error\":true,\"errorMessage\":\"collectionnotfound\",\"code\":404,\"errorNum\":1203}

--SomeBoundaryValue

HTTP/1.1404NotFound

Server:

Connection:

Content-Length:101

{\"error\":true,\"code\":404,\"errorNum\":404,\"errorMessage\":\"unknownpath'_api/collection/notexisting2'\"}

--SomeBoundaryValue--"

ReturnCodes

200:isreturnedifthebatchwasreceivedsuccessfully.HTTP200isreturnedevenifoneormultiplebatchpartactionsfailed.400:isreturnedifthebatchenvelopeismalformedorincorrectlyformatted.Thiscodewillalsobereturnedifthecontent-typeoftheoverallbatchrequestortheindividualMIMEpartsisnotasexpected.405:isreturnedwhenaninvalidHTTPmethodisused.

Examples

Sendingabatchrequestwithfivebatchparts:

GET/_api/versionDELETE/_api/collection/productsPOST/_api/collection/productsGET/_api/collection/products/figuresDELETE/_api/collection/productsTheboundary(SomeBoundaryValue)ispassedtotheserverintheHTTPContent-TypeHTTPheader.Pleasenotethereplyisnotdisplayedallaccurate.

shell>curl-XPOST--header'Content-Type:multipart/form-data;

boundary=SomeBoundaryValue'--data-binary@---dump-http://localhost:8529/_api/batch

--SomeBoundaryValue

Content-Id:myId1

GET/_api/versionHTTP/1.1

--SomeBoundaryValue

Content-Id:myId2

--SomeBoundaryValue

Content-Id:someId

BatchRequests

POST/_api/collection/productsHTTP/1.1

{"name":"products"}

--SomeBoundaryValue

Content-Id:nextId

GET/_api/collection/products/figuresHTTP/1.1

--SomeBoundaryValue

Content-Id:otherId

HTTP/1.1200OK

content-type:multipart/form-data;boundary=SomeBoundaryValue

x-arango-errors:1

"--SomeBoundaryValue\r\nContent-Type:application/x-arango-batchpart\r\nContent-Id:

myId1\r\n\r\nHTTP/1.1200OK\r\nServer:\r\nConnection:\r\nContent-Type:

application/json;charset=utf-8\r\nContent-Length:

59\r\n\r\n{\"server\":\"arango\",\"version\":\"3.3.3\",\"license\":\"community\"}\r\n--

SomeBoundaryValue\r\nContent-Type:application/x-arango-batchpart\r\nContent-Id:

myId2\r\n\r\nHTTP/1.1404NotFound\r\nServer:\r\nConnection:\r\nContent-Type:

application/json;charset=utf-8\r\nContent-Length:

79\r\n\r\n{\"error\":true,\"errorMessage\":\"collectionnot

found\",\"code\":404,\"errorNum\":1203}\r\n--SomeBoundaryValue\r\nContent-Type:

application/x-arango-batchpart\r\nContent-Id:someId\r\n\r\nHTTP/1.1200OK\r\nServer:

\r\nConnection:\r\nContent-Type:application/json;charset=utf-8\r\nContent-Length:

324\r\n\r\n{\"code\":200,\"error\":false,\"status\":3,\"statusString\":\"loaded\",\"name\"

:\"products\",\"keyOptions\":

{\"type\":\"traditional\",\"allowUserKeys\":true,\"lastValue\":0},\"type\":2,\"indexBucket

s\":8,\"globallyUniqueId\":\"h68719E5AC6E7/9990\",\"doCompact\":true,\"waitForSync\":false

,\"id\":\"9990\",\"isSystem\":false,\"journalSize\":33554432,\"isVolatile\":false}\r\n--

SomeBoundaryValue\r\nContent-Type:application/x-arango-batchpart\r\nContent-Id:

nextId\r\n\r\nHTTP/1.1200OK\r\nServer:\r\nLocation:

/_api/collection/products/figures\r\nConnection:\r\nContent-Type:application/json;

charset=utf-8\r\nContent-Length:

831\r\n\r\n{\"code\":200,\"error\":false,\"statusString\":\"loaded\",\"name\":\"products\"

,\"keyOptions\":

{\"type\":\"traditional\",\"allowUserKeys\":true,\"lastValue\":0},\"journalSize\":33554432

,\"isVolatile\":false,\"isSystem\":false,\"status\":3,\"count\":0,\"figures\":

{\"indexes\":{\"count\":1,\"size\":32128},\"documentReferences\":0,\"waitingFor\":\"-

\",\"alive\":{\"count\":0,\"size\":0},\"dead\":

{\"count\":0,\"size\":0,\"deletion\":0},\"compactionStatus\":{\"message\":\"compactionnot

yetstarted\",\"time\":\"2018-01-

25T19:13:37Z\",\"count\":0,\"filesCombined\":0,\"bytesRead\":0,\"bytesWritten\":0},\"dataf

iles\":{\"count\":0,\"fileSize\":0},\"journals\":

{\"count\":0,\"fileSize\":0},\"compactors\":{\"count\":0,\"fileSize\":0},\"revisions\":

{\"count\":0,\"size\":48192},\"lastTick\":0,\"uncollectedLogfileEntries\":0},\"doCompact\"

:true,\"globallyUniqueId\":\"h68719E5AC6E7/9990\",\"type\":2,\"indexBuckets\":8,\"waitForS

ync\":false,\"id\":\"9990\"}\r\n--SomeBoundaryValue\r\nContent-Type:application/x-arango-

BatchRequests

batchpart\r\nContent-Id:otherId\r\n\r\nHTTP/1.1200OK\r\nServer:\r\nConnection:

\r\nContent-Type:application/json;charset=utf-8\r\nContent-Length:

38\r\n\r\n{\"code\":200,\"error\":false,\"id\":\"9990\"}\r\n--SomeBoundaryValue--"

Sendingabatchrequest,settingtheboundaryimplicitly(theserverwillinthiscasetrytofindtheboundaryatthebeginningoftherequestbody).

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/batch<<EOF

--SomeBoundaryValue

DELETE/_api/collection/notexisting1HTTP/1.1

--SomeBoundaryValue

DELETE_api/collection/notexisting2HTTP/1.1

HTTP/1.1200OK

content-type:

x-arango-errors:2

"--SomeBoundaryValue\r\nContent-Type:application/x-arango-batchpart\r\n\r\nHTTP/1.1404

NotFound\r\nServer:\r\nConnection:\r\nContent-Type:application/json;charset=utf-

8\r\nContent-Length:79\r\n\r\n{\"error\":true,\"errorMessage\":\"collectionnot

found\",\"code\":404,\"errorNum\":1203}\r\n--SomeBoundaryValue\r\nContent-Type:

application/x-arango-batchpart\r\n\r\nHTTP/1.1404NotFound\r\nServer:\r\nConnection:

\r\nContent-Type:application/json;charset=utf-8\r\nContent-Length:

101\r\n\r\n{\"error\":true,\"code\":404,\"errorNum\":404,\"errorMessage\":\"unknownpath

'_api/collection/notexisting2'\"}\r\n--SomeBoundaryValue--"

BatchRequests

HTTPInterfaceforExportingDocuments

Createexportcursor

exportalldocumentsfromacollection,usingacursor

POST/_api/export

count:booleanflagthatindicateswhetherthenumberofdocumentsintheresultsetshouldbereturnedinthe"count"attributeoftheresult(optional).Calculatingthe"count"attributemightinthefuturehaveaperformanceimpactsothisoptionisturnedoffbydefault,and"count"isonlyreturnedwhenrequested.restrict:

fields(string):Containsanarrayofattributenamestoincludeorexclude.Matchingofattributenamesforinclusionorexclusionwillbedoneonthetoplevelonly.Specifyingnamesofnestedattributesisnotsupportedatthemoment.type:hastobebesettoeitherincludeorexcludedependingonwhichyouwanttouse

batchSize:maximumnumberofresultdocumentstobetransferredfromtheservertotheclientinoneroundtrip(optional).Ifthisattributeisnotset,aserver-controlleddefaultvaluewillbeused.flush:ifsettotrue,aWALflushoperationwillbeexecutedpriortotheexport.TheflushoperationwillstartcopyingdocumentsfromtheWALtothecollection'sdatafiles.TherewillbeanadditionalwaittimeofuptoflushWaitsecondsaftertheflushtoallowtheWALcollectortochangetheadjusteddocumentmeta-datatopointintothedatafiles,too.Thedefaultvalueisfalse(i.e.noflush)somostrecentlyinsertedorupdateddocumentsfromthecollectionmightbemissingintheexport.flushWait:maximumwaittimeinsecondsafteraflushoperation.Thedefaultvalueis10.Thisoptiononlyhasaneffectwhenflushissettotrue.limit:anoptionallimitvalue,determiningthemaximumnumberofdocumentstobeincludedinthecursor.Omittingthelimitattributeorsettingitto0willleadtonolimitbeingused.Ifalimitisused,itisundefinedwhichdocumentsfromthecollectionwillbeincludedintheexportandwhichwillbeexcluded.Thisisbecausethereisnonaturalorderofdocumentsinacollection.ttl:anoptionaltime-to-liveforthecursor(inseconds).Thecursorwillberemovedontheserverautomaticallyafterthespecifiedamountoftime.Thisisusefultoensuregarbagecollectionofcursorsthatarenotfullyfetchedbyclients.Ifnotset,aserver-definedvaluewillbeused.

Acalltothismethodcreatesacursorcontainingalldocumentsinthespecifiedcollection.Incontrasttootherdata-producingAPIs,theinternaldatastructuresproducedbytheexportAPIaremorelightweight,soitisthepreferredwaytoretrievealldocumentsfromacollection.

Documentsarereturnedinasimilarmannerasinthe/_api/cursorRESTAPI.Ifalldocumentsofthecollectionfitintothefirstbatch,thennocursorwillbecreated,andtheresultobject'shasMoreattributewillbesettofalse.Ifnotalldocumentsfitintothefirstbatch,thentheresultobject'shasMoreattributewillbesettotrue,andtheidattributeoftheresultwillcontainacursorid.

Theorderinwhichthedocumentsarereturnedisnotspecified.

Bydefault,onlythosedocumentsfromthecollectionwillbereturnedthatarestoredinthecollection'sdatafiles.Documentsthatarepresentinthewrite-aheadlog(WAL)atthetimetheexportisrunwillnotbeexported.

Toexportthesedocumentsaswell,thecallercanissueaWALflushrequestbeforecallingtheexportAPIorsettheflushattribute.SettingtheflushoptionwilltriggeraWALflushbeforetheexportsodocumentsgetcopiedfromtheWALtothecollectiondatafiles.

Iftheresultsetcanbecreatedbytheserver,theserverwillrespondwithHTTP201.ThebodyoftheresponsewillcontainaJSONobjectwiththeresultset.

ThereturnedJSONobjecthasthefollowingproperties:

result:anarrayofresultdocuments(mightbeemptyifthecollectionwasempty)

hasMore:abooleanindicatorwhethertherearemoreresultsavailableforthecursorontheserver

count:thetotalnumberofresultdocumentsavailable(onlyavailableifthequerywasexecutedwiththecountattributeset)

Exportingdata

id:idoftemporarycursorcreatedontheserver(optional,seeabove)

IftheJSONrepresentationismalformedorthequeryspecificationismissingfromtherequest,theserverwillrespondwithHTTP400.

Clientsshouldalwaysdeleteanexportcursorresultasearlyaspossiblebecausealingeringexportcursorwillpreventtheunderlyingcollectionfrombeingcompactedorunloaded.Bydefault,unusedcursorswillbedeletedautomaticallyafteraserver-definedidletime,andclientscanadjustthisidletimebysettingthettlvalue.

Note:thisAPIiscurrentlynotsupportedonclustercoordinators.

Exportingdata

HTTPInterfaceforIndexes

Indexes

ThisisanintroductiontoArangoDB'sHTTPinterfaceforindexesingeneral.Therearespecialsectionsforvariousindextypes.

Indexesareusedtoallowfastaccesstodocuments.Foreachcollectionthereisalwaystheprimaryindexwhichisahashindexforthedocumentkey(_keyattribute).Thisindexcannotbedroppedorchanged.edgecollectionswillalsohaveanautomaticallycreatededgesindex,whichcannotbemodified.Thisindexprovidesquickaccesstodocumentsviathe_fromand_toattributes.

Mostuser-landindexescanbecreatedbydefiningthenamesoftheattributeswhichshouldbeindexed.Someindextypesallowindexingjustoneattribute(e.g.fulltextindex)whereasotherindextypesallowindexingmultipleattributes.

Usingthesystemattribute_idinuser-definedindexesisnotsupportedbyanyindextype.

IndexHandle

Anindexhandleuniquelyidentifiesanindexinthedatabase.Itisastringandconsistsofacollectionnameandanindexidentifierseparatedby/.GeoIndex:Ageoindexisusedtofindplacesonthesurfaceoftheearthfast.HashIndex:Ahashindexisusedtofinddocumentsbasedonexamples.Ahashindexcanbecreatedforoneormultipledocumentattributes.Ahashindexwillonlybeusedbyqueriesifallindexedattributesarepresentintheexampleorsearchquery,andifallattributesarecomparedusingtheequality(==operator).Thatmeansthehashindexdoesnotsupportrangequeries.

Iftheindexisdeclaredunique,thenaccesstotheindexedattributesshouldbefast.Theperformancedegradesiftheindexedattribute(s)contain(s)onlyveryfewdistinctvalues.

EdgesIndex

Anedgesindexisautomaticallycreatedforedgecollections.Itcontainsconnectionsbetweenvertexdocumentsandisinvokedwhentheconnectingedgesofavertexarequeried.Thereisnowaytoexplicitlycreateordeleteedgeindexes.

SkiplistIndex

Askiplistisasortedindexthatcanbeusedtofindindividualdocumentsorrangesofdocuments.

PersistentIndex

Apersistentindexisasortedindexthatcanbeusedforfindingindividualdocumentsorrangesofdocuments.Inconstrasttotheotherindexes,thecontentsofapersistentindexarestoredondiskandthusdonotneedtoberebuiltinmemoryfromthedocumentswhenthecollectionisloaded.

FulltextIndex:

Afulltextindexcanbeusedtofindwords,orprefixesofwordsinsidedocuments.Afulltextindexcanbesetononeattributeonly,andwillindexallwordscontainedindocumentsthathaveatextualvalueinthisattribute.Onlywordswitha(specifiable)minimumlengthareindexed.Wordtokenizationisdoneusingthewordboundaryanalysisprovidedbylibicu,whichistakingintoaccounttheselectedlanguageprovidedatserverstart.Wordsareindexedintheirlower-casedform.Theindexsupportscompletematchqueries(fullwords)andprefixqueries.

Thebasicoperations(create,read,update,delete)fordocumentsaremappedtothestandardHTTPmethods(POST,GET,PUT,DELETE).

AddressofanIndex

Indexes

AllindexesinArangoDBhaveanuniquehandle.ThisindexhandleidentifiesanindexandismanagedbyArangoDB.AllindexesarefoundundertheURI

http://server:port/_api/index/index-handle

Forexample:Assumethattheindexhandleisdemo/63563528thentheURLofthatindexis:

http://localhost:8529/_api/index/demo/63563528

Indexes

WorkingwithIndexesusingHTTP

Readindex

returnsanindex

GET/_api/index/{index-handle}

PathParameters

index-handle(required):Theindex-handle.

Theresultisanobjectdescribingtheindex.Ithasatleastthefollowingattributes:

id:theidentifieroftheindex

type:theindextype

Allotherattributesaretype-dependent.Forexample,someindexesprovideuniqueorsparseflags,whereasothersdon't.SomeindexesalsoprovideaselectivityestimateintheselectivityEstimateattributeoftheresult.

Example:

shell>curl--dump-http://localhost:8529/_api/index/products/0

HTTP/1.1200OK

"fields":[

"_key"

"id":"products/0",

"sparse":false,

"type":"primary",

"unique":true,

"error":false,

"code":200

ReturnCodes

200:Iftheindexexists,thenaHTTP200isreturned.404:Iftheindexdoesnotexist,thenaHTTP404isreturned.

Examples

shell>curl--dump-http://localhost:8529/_api/index/products/0

HTTP/1.1200OK

showresponsebody

Createindex

createsanindex

WorkingwithIndexes

POST/_api/index#general

QueryParameters

collection(required):Thecollectionname.

Createsanewindexinthecollectioncollection.Expectsanobjectcontainingtheindexdetails.

Thetypeoftheindextobecreatedmustspecifiedinthetypeattributeoftheindexdetails.Dependingontheindextype,additionalotherattributesmayneedtospecifiedintherequestinordertocreatetheindex.

Indexesrequirethetobeindexedattribute(s)inthefieldsattributeoftheindexdetails.Dependingontheindextype,asingleattributeormultipleattributescanbeindexed.Inthelattercase,anarrayofstringsisexpected.

Indexingthesystemattribute_idisnotsupportedforuser-definedindexes.Manuallycreatinganindexusing_idasanindexattributewillfailwithanerror.

Someindexescanbecreatedasuniqueornon-uniquevariants.Uniquenesscanbecontrolledformostindexesbyspecifyingtheuniqueflagintheindexdetails.Settingittotruewillcreateauniqueindex.Settingittofalseoromittingtheuniqueattributewillcreateanon-uniqueindex.

Note:Thefollowingindextypesdonotsupportuniqueness,andusingtheuniqueattributewiththesetypesmayleadtoanerror:

geoindexesfulltextindexes

Note:Uniqueindexesonnon-shardkeysarenotsupportedinacluster.

Hash,skiplistandpersistentindexescanoptionallybecreatedinasparsevariant.Asparseindexwillbecreatedifthesparseattributeintheindexdetailsissettotrue.Sparseindexesdonotindexdocumentsforwhichanyoftheindexattributesiseithernotsetorisnull.

Theoptionalattributededuplicateissupportedbyarrayindexesoftypehashorskiplist.Itcontrolswhetherinsertingduplicateindexvaluesfromthesamedocumentintoauniquearrayindexwillleadtoauniqueconstrainterrorornot.Thedefaultvalueistrue,soonlyasingleinstanceofeachnon-uniqueindexvaluewillbeinsertedintotheindexperdocument.Tryingtoinsertavalueintotheindexthatalreadyexistsintheindexwillalwaysfail,regardlessofthevalueofthisattribute.

ReturnCodes

200:Iftheindexalreadyexists,thenanHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenanHTTP201isreturned.400:Ifaninvalidindexdescriptionispostedorattributesareusedthatthetargetindexwillnotsupport,thenanHTTP400isreturned.404:Ifcollectionisunknown,thenanHTTP404isreturned.

Deleteindex

deletesanindex

DELETE/_api/index/{index-handle}

PathParameters

index-handle(required):Theindexhandle.

Deletesanindexwithindex-handle.

Example:

shell>curl-XDELETE--dump-http://localhost:8529/_api/index/products/11938

HTTP/1.1200OK

WorkingwithIndexes

"id":"products/11938",

"error":false,

"code":200

ReturnCodes

200:Iftheindexcouldbedeleted,thenanHTTP200isreturned.404:Iftheindex-handleisunknown,thenanHTTP404isreturned.

Examples

shell>curl-XDELETE--dump-http://localhost:8529/_api/index/products/11938

HTTP/1.1200OK

showresponsebody

Readallindexesofacollection

returnsallindexesofacollection

GET/_api/index

QueryParameters

Returnsanobjectwithanattributeindexescontaininganarrayofallindexdescriptionsforthegivencollection.Thesameinformationisalsoavailableintheidentifiersasanobjectwiththeindexhandlesaskeys.

Example:Returninformationaboutallindexes

shell>curl--dump-http://localhost:8529/_api/index?collection=products

HTTP/1.1200OK

"error":false,

"code":200,

"indexes":[

"fields":[

"_key"

"id":"products/0",

"sparse":false,

"type":"primary",

"unique":true

"deduplicate":true,

"fields":[

"name"

WorkingwithIndexes

"sparse":false,

"type":"hash",

"unique":false

"deduplicate":true,

"fields":[

"price"

"sparse":true,

"type":"skiplist",

"unique":false

"identifiers":{

"products/0":{

"fields":[

"_key"

"id":"products/0",

"sparse":false,

"type":"primary",

"unique":true

"products/11780":{

"deduplicate":true,

"fields":[

"name"

"sparse":false,

"type":"hash",

"unique":false

"products/11783":{

"deduplicate":true,

"fields":[

"price"

"sparse":true,

"type":"skiplist",

"unique":false

ReturnCodes

200:returnsaJSONobjectcontainingalistofindexesonthatcollection.

Examples

Returninformationaboutallindexes

shell>curl--dump-http://localhost:8529/_api/index?collection=products

HTTP/1.1200OK

showresponsebody

WorkingwithIndexes

WorkingwithHashIndexesIfasuitablehashindexexists,then/_api/simple/by-examplewillusethisindextoexecuteaquery-by-example.

Createhashindex

createsahashindex

POST/_api/index#hash

QueryParameters

collection-name(required):Thecollectionname.

fields(string):anarrayofattributepaths.unique:iftrue,thencreateauniqueindex.type:mustbeequalto"hash" .sparse:iftrue,thencreateasparseindex.deduplicate:iffalse,thededuplicationofarrayvaluesisturnedoff.

Createsahashindexforthecollectioncollection-nameifitdoesnotalreadyexist.Thecallexpectsanobjectcontainingtheindexdetails.

Inasparseindexalldocumentswillbeexcludedfromtheindexthatdonotcontainatleastoneofthespecifiedindexattributes(i.e.fields)orthathaveavalueofnullinanyofthespecifiedindexattributes.Suchdocumentswillnotbeindexed,andnotbetakenintoaccountforuniquenesschecksiftheuniqueflagisset.

Inanon-sparseindex,thesedocumentswillbeindexed(fornon-presentindexedattributes,avalueofnullwillbeused)andwillbetakenintoaccountforuniquenesschecksiftheuniqueflagisset.

Note:uniqueindexesonnon-shardkeysarenotsupportedinacluster.

Example:Creatinganuniqueconstraint

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?collection=products<<EOF

"type":"hash",

"unique":true,

"fields":[

HTTP/1.1201Created

"deduplicate":true,

"fields":[

"isNewlyCreated":true,

"sparse":false,

"type":"hash",

"unique":true,

"error":false,

"code":201

Example:Creatinganon-uniquehashindex

"type":"hash",

"unique":false,

"fields":[

HTTP/1.1201Created

"deduplicate":true,

"fields":[

"sparse":false,

"type":"hash",

"unique":false,

"error":false,

"code":201

Example:Creatingasparseindex

"type":"hash",

"unique":false,

"sparse":true,

"fields":[

HTTP/1.1201Created

"deduplicate":true,

"fields":[

"sparse":true,

"type":"hash",

"unique":false,

"error":false,

"code":201

ReturnCodes

200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.400:Ifthecollectionalreadycontainsdocumentsandyoutrytocreateauniquehashindexinsuchawaythattherearedocumentsviolatingtheuniqueness,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Examples

Creatinganuniqueconstraint

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/index?

"type":"hash",

"unique":true,

"fields":[

HTTP/1.1201Created

showresponsebodyCreatinganon-uniquehashindex

"type":"hash",

"unique":false,

"fields":[

HTTP/1.1201Created

showresponsebodyCreatingasparseindex

"type":"hash",

"unique":false,

"sparse":true,

"fields":[

HTTP/1.1201Created

showresponsebody

Simplequeryby-example

returnsalldocumentsofacollectionmatchingagivenexample

PUT/_api/simple/by-example

skip:Thenumberofdocumentstoskipinthequery(optional).batchSize:maximumnumberofresultdocumentstobetransferredfromtheservertotheclientinoneroundtrip.Ifthisattributeisnotset,aserver-controlleddefaultvaluewillbeused.AbatchSizevalueof0isdisallowed.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)example:Theexampledocument.collection:Thenameofthecollectiontoquery.

Thiswillfindalldocumentsmatchingagivenexample.

Example:Matchinganattribute

"example":{

HTTP/1.1201Created

"result":[

"_key":"12208",

"_rev":"_WQ47fbm--_",

"k":2,

"_key":"12202",

"_rev":"_WQ47fbi--B",

"_key":"12198",

"_rev":"_WQ47fbi--_",

"k":1,

"_key":"12205",

"_rev":"_WQ47fbi--D",

"hasMore":false,

"count":4,

"error":false,

"code":201

Example:Matchinganattributewhichisasub-document

"example":{

"a.j":1

HTTP/1.1201Created

"result":[

"_key":"12228",

"_rev":"_WQ47fcK--B",

"_key":"12224",

"_rev":"_WQ47fcK--_",

"k":1,

"hasMore":false,

"count":2,

"error":false,

"code":201

Example:Matchinganattributewithinasub-document

"example":{

HTTP/1.1201Created

"result":[

"_key":"12254",

"_rev":"_WQ47fcq--B",

"hasMore":false,

"count":1,

"error":false,

"code":201

ReturnCodes

Examples

Matchinganattribute

"example":{

HTTP/1.1201Created

showresponsebodyMatchinganattributewhichisasub-document

"example":{

"a.j":1

HTTP/1.1201Created

showresponsebodyMatchinganattributewithinasub-document

"example":{

HTTP/1.1201Created

showresponsebody

Finddocumentsmatchinganexample

returnsonedocumentofacollectionmatchingagivenexample

PUT/_api/simple/first-example

example:Theexampledocument.collection:Thenameofthecollectiontoquery.

Thiswillreturnthefirstdocumentmatchingagivenexample.

ReturnsaresultcontainingthedocumentorHTTP404ifnodocumentmatchedtheexample.

Ifmorethanonedocumentinthecollectionmatchesthespecifiedexample,onlyoneofthesedocumentswillbereturned,anditisundefinedwhichofthematchingdocumentsisreturned.

Example:Ifamatchingdocumentwasfound

"example":{

HTTP/1.1200OK

"document":{

"_key":"12286",

"_rev":"_WQ47fdO--F",

"k":2,

"error":false,

"code":200

Example:Ifnodocumentwasfound

"example":{

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":404,

"errorMessage":"nomatch"

ReturnCodes

200:isreturnedwhenthequerywassuccessfullyexecuted.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocument

inthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.

Examples

Ifamatchingdocumentwasfound

example<<EOF

"example":{

HTTP/1.1200OK

showresponsebodyIfnodocumentwasfound

example<<EOF

"example":{

HTTP/1.1404NotFound

showresponsebody

WorkingwithSkiplistIndexesIfasuitableskip-listindexexists,then/_api/simple/rangeandotheroperationswillusethisindextoexecutequeries.

Createskiplist

createsaskip-list

POST/_api/index#skiplist

QueryParameters

fields(string):anarrayofattributepaths.unique:iftrue,thencreateauniqueindex.type:mustbeequalto"skiplist" .sparse:iftrue,thencreateasparseindex.deduplicate:iffalse,thededuplicationofarrayvaluesisturnedoff.

Createsaskip-listindexforthecollectioncollection-name,ifitdoesnotalreadyexist.Thecallexpectsanobjectcontainingtheindexdetails.

Example:Creatingaskiplistindex

"type":"skiplist",

"unique":false,

"fields":[

HTTP/1.1201Created

"deduplicate":true,

"fields":[

"sparse":false,

"type":"skiplist",

"unique":false,

"error":false,

Skiplist

"code":201

Example:Creatingasparseskiplistindex

"type":"skiplist",

"unique":false,

"sparse":true,

"fields":[

HTTP/1.1201Created

"deduplicate":true,

"fields":[

"sparse":true,

"type":"skiplist",

"unique":false,

"error":false,

"code":201

ReturnCodes

200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.400:Ifthecollectionalreadycontainsdocumentsandyoutrytocreateauniqueskip-listindexinsuchawaythattherearedocumentsviolatingtheuniqueness,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Examples

Creatingaskiplistindex

"type":"skiplist",

"unique":false,

"fields":[

HTTP/1.1201Created

Skiplist

showresponsebodyCreatingasparseskiplistindex

"type":"skiplist",

"unique":false,

"sparse":true,

"fields":[

HTTP/1.1201Created

showresponsebody

Skiplist

WorkingwithPersistentIndexesIfasuitablepersistentindexexists,then/_api/simple/rangeandotheroperationswillusethisindextoexecutequeries.

Createapersistentindex

createsapersistentindex

POST/_api/index#persistent

QueryParameters

fields(string):anarrayofattributepaths.unique:iftrue,thencreateauniqueindex.type:mustbeequalto"persistent" .sparse:iftrue,thencreateasparseindex.

Createsapersistentindexforthecollectioncollection-name,ifitdoesnotalreadyexist.Thecallexpectsanobjectcontainingtheindexdetails.

Example:Creatingapersistentindex

"type":"persistent",

"unique":false,

"fields":[

HTTP/1.1201Created

"deduplicate":true,

"fields":[

"sparse":false,

"unique":false,

"error":false,

"code":201

Persistent

Example:Creatingasparsepersistentindex

"unique":false,

"sparse":true,

"fields":[

HTTP/1.1201Created

"deduplicate":true,

"fields":[

"sparse":true,

"unique":false,

"error":false,

"code":201

ReturnCodes

200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.400:Ifthecollectionalreadycontainsdocumentsandyoutrytocreateauniquepersistentindexinsuchawaythattherearedocumentsviolatingtheuniqueness,thenaHTTP400isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Examples

Creatingapersistentindex

"unique":false,

"fields":[

HTTP/1.1201Created

Persistent

showresponsebodyCreatingasparsepersistentindex

"unique":false,

"sparse":true,

"fields":[

HTTP/1.1201Created

showresponsebody

Persistent

WorkingwithGeoIndexes

Creategeo-spatialindex

createsageoindex

POST/_api/index#geo

QueryParameters

fields(string):Anarraywithoneortwoattributepaths.Ifitisanarraywithoneattributepathlocation,thenageo-spatialindexonalldocumentsiscreatedusinglocationaspathtothecoordinates.Thevalueoftheattributemustbeanarraywithatleasttwodoublevalues.Thearraymustcontainthelatitude(firstvalue)andthelongitude(secondvalue).Alldocuments,whichdonothavetheattributepathorwithvaluethatarenotsuitable,areignored.Ifitisanarraywithtwoattributepathslatitudeandlongitude,thenageo-spatialindexonalldocumentsiscreatedusinglatitudeandlongitudeaspathsthelatitudeandthelongitude.Thevalueoftheattributelatitudeandoftheattributelongitudemustadouble.Alldocuments,whichdonothavetheattributepathsorwhichvaluesarenotsuitable,areignored.type:mustbeequalto"geo" .geoJson:Ifageo-spatialindexonalocationisconstructedandgeoJsonistrue,thentheorderwithinthearrayislongitudefollowedbylatitude.Thiscorrespondstotheformatdescribedinhttp://geojson.org/geojson-spec.html#positions

Createsageo-spatialindexinthecollectioncollection-name,ifitdoesnotalreadyexist.Expectsanobjectcontainingtheindexdetails.

Geoindexesarealwayssparse,meaningthatdocumentsthatdonotcontaintheindexattributesorhavenon-numericvaluesintheindexattributeswillnotbeindexed.

Example:Creatingageoindexwithalocationattribute

"type":"geo",

"fields":[

HTTP/1.1201Created

"constraint":false,

"fields":[

"geoJson":false,

"ignoreNull":true,

"sparse":true,

"type":"geo1",

"unique":false,

"error":false,

"code":201

Example:Creatingageoindexwithlatitudeandlongitudeattributes

"type":"geo",

"fields":[

HTTP/1.1201Created

"constraint":false,

"fields":[

"ignoreNull":true,

"sparse":true,

"type":"geo2",

"unique":false,

"error":false,

"code":201

ReturnCodes

200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Examples

Creatingageoindexwithalocationattribute

"type":"geo",

"fields":[

HTTP/1.1201Created

showresponsebodyCreatingageoindexwithlatitudeandlongitudeattributes

"type":"geo",

"fields":[

HTTP/1.1201Created

showresponsebody

Returnsdocumentsnearacoordinate

returnsalldocumentsofacollectionnearagivenlocation

PUT/_api/simple/near

distance:Ifgiven,theattributekeyusedtoreturnthedistancetothegivencoordinate.(optional).Ifspecified,distancesarereturnedinmeters.skip:Thenumberofdocumentstoskipinthequery.(optional)longitude:Thelongitudeofthecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)collection:Thenameofthecollectiontoquery.latitude:Thelatitudeofthecoordinate.geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)

Thedefaultwillfindatmost100documentsnearthegivencoordinate.Thereturnedarrayissortedaccordingtothedistance,withthenearestdocumentbeingfirstinthereturnarray.Ifthereareneardocumentsofequaldistance,documentsarechosenrandomlyfromthissetuntilthelimitisreached.

Inordertousethenearoperator,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.

Note:thenearsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheNEARfunctionasfollows:

FORdocINNEAR(@@collection,@latitude,@longitude,@limit)

RETURNdoc`

"latitude":0,

"longitude":0,

"skip":1,

"limit":2

HTTP/1.1201Created

"result":[

"_key":"12441",

"_rev":"_WQ47fgq--D",

"name":"Name/0.002/",

"loc":[

0.002,

"_key":"12435",

"_rev":"_WQ47fgq--_",

"name":"Name/-0.002/",

"loc":[

-0.002,

"hasMore":false,

"count":2,

"error":false,

"code":201

"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

HTTP/1.1201Created

"result":[

"distance":222.38985328911744,

"_key":"12486",

"_rev":"_WQ47fhq--D",

"loc":[

-0.002,

"name":"Name/-0.002/"

"distance":222.38985328911744,

"_key":"12492",

"_rev":"_WQ47fhq--H",

"loc":[

0.002,

"distance":444.779706578235,

"_key":"12483",

"_rev":"_WQ47fhq--B",

"loc":[

-0.004,

"name":"Name/-0.004/"

"hasMore":false,

"count":3,

"error":false,

"code":201

ReturnCodes

Examples

Withoutdistance

"latitude":0,

"longitude":0,

"skip":1,

"limit":2

HTTP/1.1201Created

"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

HTTP/1.1201Created

showresponsebody

Finddocumentswithinaradiusaroundacoordinate

returnsalldocumentsofacollectionwithinagivenradius

PUT/_api/simple/within

distance:Ifgiven,theattributekeyusedtoreturnthedistancetothegivencoordinate.(optional).Ifspecified,distancesarereturnedinmeters.skip:Thenumberofdocumentstoskipinthequery.(optional)longitude:Thelongitudeofthecoordinate.radius:Themaximalradius(inmeters).collection:Thenameofthecollectiontoquery.latitude:Thelatitudeofthecoordinate.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.Thedefaultis100.(optional)geo:Ifgiven,theidentifierofthegeo-indextouse.(optional)

Thiswillfindalldocumentswithinagivenradiusaroundthecoordinate(latitude,longitude).Thereturnedlistissortedbydistance.

Inordertousethewithinoperator,ageoindexmustbedefinedforthecollection.Thisindexalsodefineswhichattributeholdsthecoordinatesforthedocument.Ifyouhavemorethanonegeo-spatialindex,youcanusethegeofieldtoselectaparticularindex.

Note:thewithinsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheWITHINfunctionasfollows:

FORdocINWITHIN(@@collection,@latitude,@longitude,@radius,@distanceAttributeName)

RETURNdoc

"latitude":0,

"longitude":0,

"skip":1,

"limit":2,

"radius":500

HTTP/1.1201Created

"result":[

"_key":"12854",

"_rev":"_WQ47foi--_",

"name":"Name/0.002/",

"loc":[

0.002,

"_key":"12848",

"_rev":"_WQ47foe--H",

"name":"Name/-0.002/",

"loc":[

-0.002,

"hasMore":false,

"count":2,

"error":false,

"code":201

"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

"radius":300

HTTP/1.1201Created

"result":[

"distance":222.38985328911744,

"_key":"12899",

"_rev":"_WQ47fpW--B",

"loc":[

-0.002,

"name":"Name/-0.002/"

"distance":222.38985328911744,

"_key":"12905",

"_rev":"_WQ47fpW--F",

"loc":[

0.002,

"distance":444.779706578235,

"_key":"12896",

"_rev":"_WQ47fpW--_",

"loc":[

-0.004,

"name":"Name/-0.004/"

"hasMore":false,

"count":3,

"error":false,

"code":201

ReturnCodes

Examples

Withoutdistance

"latitude":0,

"longitude":0,

"skip":1,

"limit":2,

"radius":500

HTTP/1.1201Created

"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

"radius":300

HTTP/1.1201Created

showresponsebody

FulltextIfafulltextindexexists,then/_api/simple/fulltextwillusethisindextoexecutethespecifiedfulltextquery.

Createfulltextindex

createsafulltextindex

POST/_api/index#fulltext

QueryParameters

fields(string):anarrayofattributenames.Currently,thearrayislimitedtoexactlyoneattribute.type:mustbeequalto"fulltext" .minLength:Minimumcharacterlengthofwordstoindex.Willdefaulttoaserver-definedvalueifunspecified.Itisthusrecommendedtosetthisvalueexplicitlywhencreatingtheindex.

Createsafulltextindexforthecollectioncollection-name,ifitdoesnotalreadyexist.Thecallexpectsanobjectcontainingtheindexdetails.

Example:Creatingafulltextindex

"type":"fulltext",

"fields":[

"text"

HTTP/1.1201Created

"fields":[

"text"

"minLength":2,

"sparse":true,

"type":"fulltext",

"unique":false,

"error":false,

"code":201

ReturnCodes

200:Iftheindexalreadyexists,thenaHTTP200isreturned.201:Iftheindexdoesnotalreadyexistandcouldbecreated,thenaHTTP201isreturned.404:Ifthecollection-nameisunknown,thenaHTTP404isreturned.

Examples

Fulltext

Creatingafulltextindex

"type":"fulltext",

"fields":[

"text"

HTTP/1.1201Created

showresponsebody

Fulltextindexquery

returnsdocumentsofacollectionasaresultofafulltextquery

PUT/_api/simple/fulltext

index:Theidentifierofthefulltext-indextouse.attribute:Theattributethatcontainsthetexts.collection:Thenameofthecollectiontoquery.limit:Themaximalamountofdocumentstoreturn.Theskipisappliedbeforethelimitrestriction.(optional)skip:Thenumberofdocumentstoskipinthequery(optional).query:Thefulltextquery.PleaserefertoFulltextqueriesfordetails.

Thiswillfindalldocumentsfromthecollectionthatmatchthefulltextqueryspecifiedinquery.

Inordertousethefulltextoperator,afulltextindexmustbedefinedforthecollectionandthespecifiedattribute.

Note:thefulltextsimplequeryisdeprecatedasofArangoDB2.6.ThisAPImayberemovedinfutureversionsofArangoDB.ThepreferredwayforretrievingdocumentsfromacollectionusingthenearoperatoristoissueanAQLqueryusingtheFULLTEXTAQLfunctionasfollows:

FORdocINFULLTEXT(@@collection,@attributeName,@queryString,@limit)

RETURNdoc

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/fulltext<<EOF

"attribute":"text",

"query":"word"

HTTP/1.1201Created

Fulltext

"result":[

"_key":"12326",

"_rev":"_WQ47feO--_",

"text":"thistextcontainsword"

"_key":"12330",

"_rev":"_WQ47feS--_",

"text":"thistextalsohasaword"

"hasMore":false,

"count":2,

"error":false,

"code":201

ReturnCodes

Examples

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/simple/fulltext

"attribute":"text",

"query":"word"

HTTP/1.1201Created

showresponsebody

Fulltext

HTTPInterfaceforTransactions

Transactions

ArangoDB'stransactionsareexecutedontheserver.Transactionscanbeinitiatedbyclientsbysendingthetransactiondescriptionforexecutiontotheserver.

TransactionsinArangoDBdonotofferseparateBEGIN,COMMITandROLLBACKoperationsastheyareavailableinmanyotherdatabaseproducts.Instead,ArangoDBtransactionsaredescribedbyaJavaScriptfunction,andthecodeinsidetheJavaScriptfunctionwillthenbeexecutedtransactionally.Attheendofthefunction,thetransactionisautomaticallycommitted,andallchangesdonebythetransactionwillbepersisted.Ifanexceptionisthrownduringtransactionexecution,alloperationsperformedinthetransactionarerolledback.

ForamoredetaileddescriptionofhowtransactionsworkinArangoDBpleaserefertoTransactions.

Executetransaction

executeaserver-sidetransaction

POST/_api/transaction

maxTransactionSize:Transactionsizelimitinbytes.HonoredbytheRocksDBstorageengineonly.lockTimeout:anoptionalnumericvaluethatcanbeusedtosetatimeoutforwaitingoncollectionlocks.Ifnotspecified,adefaultvaluewillbeused.SettinglockTimeoutto0willmakeArangoDBnottimeoutwaitingforalock.waitForSync:anoptionalbooleanflagthat,ifset,willforcethetransactiontowritealldatatodiskbeforereturning.intermediateCommitCount:Maximumnumberofoperationsafterwhichanintermediatecommitisperformedautomatically.HonoredbytheRocksDBstorageengineonly.params:optionalargumentspassedtoaction.intermediateCommitSize:Maximumtotalsizeofoperationsafterwhichanintermediatecommitisperformedautomatically.HonoredbytheRocksDBstorageengineonly.action:theactualtransactionoperationstobeexecuted,intheformofstringifiedJavaScriptcode.Thecodewillbeexecutedonserverside,withlatebinding.Itisthuscriticalthatthecodespecifiedinactionproperlysetsupallthevariablesitneeds.Ifthecodespecifiedinactionendswithareturnstatement,thevaluereturnedwillalsobereturnedbytheRESTAPIintheresultattributeifthetransactioncommittedsuccessfully.collections:collectionsmustbeaJSONobjectthatcanhaveeitherorbothsub-attributesreadandwrite,eachbeinganarrayofcollectionnamesorasinglecollectionnameasstring.Collectionsthatwillbewrittentointhetransactionmustbedeclaredwiththewriteattributeoritwillfail,whereasnon-declaredcollectionsfromwhichissolelyreadwillbeaddedlazily.Theoptionalsub-attributeallowImplicitcanbesettofalsetolettransactionsfailincaseofundeclaredcollectionsforreading.Collectionsforreadingshouldbefullydeclaredifpossible,toavoiddeadlocks.

ThetransactiondescriptionmustbepassedinthebodyofthePOSTrequest.

Ifthetransactionisfullyexecutedandcommittedontheserver,HTTP200willbereturned.Additionally,thereturnvalueofthecodedefinedinactionwillbereturnedintheresultattribute.

Forsuccessfullycommittedtransactions,thereturnedJSONobjecthasthefollowingproperties:

error:booleanflagtoindicateifanerroroccurred(falseinthiscase)

result:thereturnvalueofthetransaction

Ifthetransactionspecificationiseithermissingormalformed,theserverwillrespondwithHTTP400.

ThebodyoftheresponsewillthencontainaJSONobjectwithadditionalerrordetails.Theobjecthasthefollowingattributes:

Transactions

Ifatransactionfailstocommit,eitherbyanexceptionthrownintheactioncode,orbyaninternalerror,theserverwillrespondwithanerror.AnyothererrorswillbereturnedwithanyofthereturncodesHTTP400,HTTP409,orHTTP500.

Example:Executingatransactiononasinglecollection

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/transaction<<EOF

"collections":{

"write":"products"

"action":"function(){vardb=require('@arangodb').db;db.products.save({});returndb.products.count();}"

HTTP/1.1200OK

"error":false,

"code":200,

"result":1

Example:Executingatransactionusingmultiplecollections

"collections":{

"write":[

"products",

"materials"

"action":"function(){vardb=require('@arangodb').db;db.products.save({});db.materials.save({});return'worked!';}"

HTTP/1.1200OK

"error":false,

"code":200,

"result":"worked!"

Example:Abortingatransactionduetoaninternalerror

"collections":{

"write":"products"

Transactions

"action":"function(){vardb=require('@arangodb').db;db.products.save({_key:'abc'});db.products.save({_key:'abc'});}

HTTP/1.1409Conflict

"error":true,

"errorMessage":"uniqueconstraintviolated-inindex0oftypeprimaryover[\"_key\"];conflictingkey:abc",

"code":409,

"errorNum":1210

Example:Abortingatransactionbyexplicitlythrowinganexception

"collections":{

"read":"products"

"action":"function(){throw'doh!';}"

"error":true,

"errorMessage":"transactionnotrunningoncommit",

"code":500,

"errorNum":1650

Example:Referringtoanon-existingcollection

"collections":{

"read":"products"

"action":"function(){returntrue;}"

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":1203

ReturnCodes

Transactions

200:Ifthetransactionisfullyexecutedandcommittedontheserver,HTTP200willbereturned.400:Ifthetransactionspecificationiseithermissingormalformed,theserverwillrespondwithHTTP400.404:Ifthetransactionspecificationcontainsanunknowncollection,theserverwillrespondwithHTTP404.500:ExceptionsthrownbyuserswillmaketheserverrespondwithareturncodeofHTTP500

Examples

Executingatransactiononasinglecollection

"collections":{

"write":"products"

"action":"function(){vardb=require('@arangodb').db;db.products.save({});

returndb.products.count();}"

HTTP/1.1200OK

showresponsebodyExecutingatransactionusingmultiplecollections

"collections":{

"write":[

"products",

"materials"

"action":"function(){vardb=

require('@arangodb').db;db.products.save({});db.materials.save({});return'worked!';}"

HTTP/1.1200OK

showresponsebodyAbortingatransactionduetoaninternalerror

"collections":{

"write":"products"

"action":"function(){vardb=require('@arangodb').db;db.products.save({_key:

'abc'});db.products.save({_key:'abc'});}"

Transactions

HTTP/1.1409Conflict

showresponsebodyAbortingatransactionbyexplicitlythrowinganexception

"collections":{

"read":"products"

"action":"function(){throw'doh!';}"

showresponsebodyReferringtoanon-existingcollection

"collections":{

"read":"products"

"action":"function(){returntrue;}"

HTTP/1.1404NotFound

showresponsebody

Transactions

HTTPInterfaceforReplication

Replication

ThisisanintroductiontoArangoDB'sHTTPreplicationinterface.ThereplicationarchitectureandcomponentsaredescribedinmoredetailsinReplication.

TheHTTPreplicationinterfaceservesfourmainpurposes:

fetchinitialdatafromaserver(e.g.forabackup,orfortheinitialsynchronizationofdatabeforestartingthecontinuousreplicationapplier)queryingthestateofamasterfetchcontinuouschangesfromamaster(usedforincrementalsynchronizationofchanges)administerthereplicationapplier(starting,stopping,configuring,queryingstate)onaslave

Pleasenotethatallreplicationoperationsworkonaper-databaselevel.IfanArangoDBservercontainsmorethanonedatabase,thereplicationsystemmustbeconfiguredindividuallyperdatabase,andreplicatingthedataofmultipledatabaseswillrequiremultipleoperations.

Replication

ReplicationDumpCommandsTheinventorymethodcanbeusedtoqueryanArangoDBdatabase'scurrentsetofcollectionsplustheirindexes.Clientscanusethismethodtogetanoverviewofwhichcollectionsarepresentinthedatabase.Theycanusethisinformationtoeitherstartafullorapartialsynchronizationofdata,e.g.toinitiateabackuportheincrementaldatasynchronization.

Returninventoryofcollectionsandindexes

Returnsanoverviewofcollectionsandtheirindexes

GET/_api/replication/inventory

QueryParameters

includeSystem(optional):Includesystemcollectionsintheresult.Thedefaultvalueistrue.

Returnsthearrayofcollectionsandindexesavailableontheserver.Thisarraycanbeusedbyreplicationclientstoinitiateaninitialsyncwiththeserver.

TheresponsewillcontainaJSONobjectwiththecollectionandstateandtickattributes.

collectionsisanarrayofcollectionswiththefollowingsub-attributes:

parameters:thecollectionproperties

indexes:anarrayoftheindexesofathecollection.Primaryindexesandedgeindexesarenotincludedinthisarray.

Thestateattributecontainsthecurrentstateofthereplicationlogger.Itcontainsthefollowingsub-attributes:

running:whetherornotthereplicationloggeriscurrentlyactive.Note:sinceArangoDB2.2,thevaluewillalwaysbetrue

lastLogTick:thevalueofthelasttickthereplicationloggerhaswritten

time:thecurrenttimeontheserver

ReplicationclientsshouldnotethelastLogTickvaluereturned.Theycanthenfetchcollections'datausingthedumpmethoduptothevalueoflastLogTick,andquerythecontinuousreplicationlogforlogeventsafterthistickvalue.

Tocreateafullcopyofthecollectionsontheserver,areplicationclientcanexecutethesesteps:

callthe/inventoryAPImethod.ThisreturnsthelastLogTickvalueandthearrayofcollectionsandindexesfromtheserver.

foreachcollectionreturnedby/inventory,createthecollectionlocallyandcall/dumptostreamthecollectiondatatotheclient,uptothevalueoflastLogTick.Afterthat,theclientcancreatetheindexesonthecollectionsastheywerereportedby/inventory.

Iftheclientswantstocontinuouslystreamreplicationlogeventsfromtheloggerserver,thefollowingadditionalstepsneedtobecarriedout:

theclientshouldcall/logger-followinitiallytofetchthefirstbatchofreplicationeventsthatwereloggedaftertheclient'scallto/inventory.

Thecallto/logger-followshoulduseafromparameterwiththevalueofthelastLogTickasreportedby/inventory.Thecallto/logger-followwillreturnthex-arango-replication-lastincludedwhichwillcontainthelasttickvalueincludedintheresponse.

theclientcanthencontinuouslycall/logger-followtoincrementallyfetchnewreplicationeventsthatoccurredafterthelasttransfer.

Callsshoulduseafromparameterwiththevalueofthex-arango-replication-lastincludedheaderofthepreviousresponse.Iftherearenomorereplicationevents,theresponsewillbeemptyandclientscangotosleepforawhileandtryagainlater.

Note:onacoordinator,thisrequestmusthavethequeryparameterDBserverwhichmustbeanIDofaDBserver.TheverysamerequestisforwardedsynchronouslytothatDBserver.Itisanerrorifthisattributeisnotboundinthecoordinatorcase.

Example:

ReplicationDump

shell>curl--dump-http://localhost:8529/_api/replication/inventory

HTTP/1.1200OK

"collections":[

"indexes":[],

"parameters":{

"cid":"60",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_appbundles",

"id":"60",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"numberOfShards":1,

"planId":"60",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"26",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_aqlfunctions",

"id":"26",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

ReplicationDump

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"numberOfShards":1,

"planId":"26",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"43",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_frontend",

"id":"43",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"_frontend",

"numberOfShards":1,

"planId":"43",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

ReplicationDump

"parameters":{

"cid":"2",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_graphs",

"id":"2",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"_graphs",

"numberOfShards":1,

"planId":"2",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"11",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_modules",

"id":"11",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":9899

ReplicationDump

"name":"_modules",

"numberOfShards":1,

"planId":"11",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"13",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_routing",

"id":"13",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":9948

"name":"_routing",

"numberOfShards":1,

"planId":"13",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[

"id":"9",

"type":"hash",

"fields":[

"user"

"unique":true,

"sparse":true,

"deduplicate":true

ReplicationDump

"parameters":{

"cid":"6",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_users",

"id":"6",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"id":"9",

"type":"hash",

"fields":[

"user"

"unique":true,

"sparse":true,

"deduplicate":true

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":11963

"name":"_users",

"numberOfShards":1,

"planId":"6",

"shardKeys":[

"user"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"98",

"count":0,

"deleted":false,

"doCompact":true,

"id":"98",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

ReplicationDump

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":false,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"animals",

"numberOfShards":1,

"planId":"98",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"92",

"count":0,

"deleted":false,

"doCompact":true,

"id":"92",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":false,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"demo",

"numberOfShards":1,

"planId":"92",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

ReplicationDump

"state":{

"running":true,

"lastLogTick":"12006",

"lastUncommittedLogTick":"12016",

"totalEvents":4132,

"time":"2018-01-25T19:13:45Z"

"tick":"12016"

Example:Withsomeadditionalindexes:

HTTP/1.1200OK

"collections":[

"indexes":[

"id":"12021",

"type":"hash",

"fields":[

"name"

"unique":false,

"sparse":false,

"deduplicate":true

"id":"12024",

"type":"skiplist",

"fields":[

"unique":true,

"sparse":false,

"deduplicate":true

"parameters":{

"cid":"12017",

"count":0,

"deleted":false,

"doCompact":true,

"id":"12017",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"id":"12021",

"type":"hash",

"fields":[

"name"

ReplicationDump

"unique":false,

"sparse":false,

"deduplicate":true

"id":"12024",

"type":"skiplist",

"fields":[

"unique":true,

"sparse":false,

"deduplicate":true

"isSmart":false,

"isSystem":false,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"IndexedCollection1",

"numberOfShards":1,

"planId":"12017",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[

"id":"12030",

"type":"fulltext",

"fields":[

"text"

"unique":false,

"sparse":true,

"minLength":10

"id":"12033",

"type":"skiplist",

"fields":[

"unique":false,

"sparse":false,

"deduplicate":true

"parameters":{

"cid":"12026",

"count":0,

"deleted":false,

"doCompact":true,

"id":"12026",

"indexBuckets":8,

"indexes":[

ReplicationDump

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"id":"12030",

"type":"fulltext",

"fields":[

"text"

"unique":false,

"sparse":true,

"minLength":10

"id":"12033",

"type":"skiplist",

"fields":[

"unique":false,

"sparse":false,

"deduplicate":true

"isSmart":false,

"isSystem":false,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"IndexedCollection2",

"numberOfShards":1,

"planId":"12026",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"60",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_appbundles",

"id":"60",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

ReplicationDump

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"numberOfShards":1,

"planId":"60",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"26",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_aqlfunctions",

"id":"26",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"numberOfShards":1,

"planId":"26",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

ReplicationDump

"cid":"43",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_frontend",

"id":"43",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"_frontend",

"numberOfShards":1,

"planId":"43",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"2",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_graphs",

"id":"2",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"_graphs",

ReplicationDump

"numberOfShards":1,

"planId":"2",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"11",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_modules",

"id":"11",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":9899

"name":"_modules",

"numberOfShards":1,

"planId":"11",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"13",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_routing",

"id":"13",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

ReplicationDump

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":9948

"name":"_routing",

"numberOfShards":1,

"planId":"13",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[

"id":"9",

"type":"hash",

"fields":[

"user"

"unique":true,

"sparse":true,

"deduplicate":true

"parameters":{

"cid":"6",

"count":0,

"deleted":false,

"doCompact":true,

"globallyUniqueId":"_users",

"id":"6",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"id":"9",

"type":"hash",

"fields":[

"user"

"unique":true,

"sparse":true,

"deduplicate":true

ReplicationDump

"isSmart":false,

"isSystem":true,

"isVolatile":false,

"keyOptions":{

"lastValue":11963

"name":"_users",

"numberOfShards":1,

"planId":"6",

"shardKeys":[

"user"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

"cid":"98",

"count":0,

"deleted":false,

"doCompact":true,

"id":"98",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":false,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"animals",

"numberOfShards":1,

"planId":"98",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"indexes":[],

"parameters":{

ReplicationDump

"cid":"92",

"count":0,

"deleted":false,

"doCompact":true,

"id":"92",

"indexBuckets":8,

"indexes":[

"id":"0",

"type":"primary",

"fields":[

"_key"

"unique":true,

"sparse":false

"isSmart":false,

"isSystem":false,

"isVolatile":false,

"keyOptions":{

"lastValue":0

"name":"demo",

"numberOfShards":1,

"planId":"92",

"shardKeys":[

"_key"

"shards":{

"status":3,

"type":2,

"version":6,

"waitForSync":false

"state":{

"running":true,

"totalEvents":4138,

"time":"2018-01-25T19:13:45Z"

"tick":"12034"

ReturnCodes

200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.

Examples

HTTP/1.1200OK

showresponsebody

ReplicationDump

Withsomeadditionalindexes:

HTTP/1.1200OK

showresponsebodyThebatchmethodwillcreateasnapshotofthecurrentstatethatthencanbedumped.AbatchIdisrequiredwhenusingthedumpapiwithrocksdb.

Createnewdumpbatch

handleadumpbatchcommand

POST/_api/replication/batchNote:Thesecallsareuninterestingtousers.

ttl:thetime-to-liveforthenewbatch(inseconds)AJSONobjectwiththebatchconfiguration.

Createsanewdumpbatchandreturnsthebatch'sid.

id:theidofthebatch

ReturnCodes

200:isreturnedifthebatchwascreatedsuccessfully.400:isreturnedifthettlvalueisinvalidorifDBserverattributeisnotspecifiedorillegalonacoordinator.405:isreturnedwhenaninvalidHTTPmethodisused.

Deletesanexistingdumpbatch

DELETE/_api/replication/batch/{id}Note:Thesecallsareuninterestingtousers.

PathParameters

id(required):Theidofthebatch.

Deletestheexistingdumpbatch,allowingcompactionandcleanuptoresume.

ReturnCodes

204:isreturnedifthebatchwasdeletedsuccessfully.400:isreturnedifthebatchwasnotfound.405:isreturnedwhenaninvalidHTTPmethodisused.

Prolongexistingdumpbatch

PUT/_api/replication/batch/{id}Note:Thesecallsareuninterestingtousers.

ReplicationDump

ttl:thetime-to-liveforthenewbatch(inseconds)

Extendsthettlofanexistingdumpbatch,usingthebatch'sidandtheprovidedttlvalue.

Ifthebatch'sttlcanbeextendedsuccessfully,theresponseisempty.

PathParameters

id(required):Theidofthebatch.

ReturnCodes

204:isreturnedifthebatch'sttlwasextendedsuccessfully.400:isreturnedifthettlvalueisinvalidorthebatchwasnotfound.405:isreturnedwhenaninvalidHTTPmethodisused.Thedumpmethodcanbeusedtofetchdatafromaspecificcollection.Astheresultsofthedumpcommandcanbehuge,dumpmaynotreturnalldatafromacollectionatonce.Instead,thedumpcommandmaybecalledrepeatedlybyreplicationclientsuntilthereisnomoredatatofetch.Thedumpcommandwillnotonlyreturnthecurrentdocumentsinthecollection,butalsodocumentupdatesanddeletions.

Pleasenotethatthedumpmethodwillonlyreturndocuments,updatesanddeletionsfromacollection'sjournalsanddatafiles.Operationsthatarestoredinthewrite-aheadlogonlywillnotbereturned.Inordertoensurethattheseoperationsareincludedinadump,thewrite-aheadlogmustbeflushedfirst.

Togettoanidenticalstateofdata,replicationclientsshouldapplytheindividualpartsofthedumpresultsinthesameorderastheyareprovided.

Returndataofacollection

returnsthewholecontentofonecollection

GET/_api/replication/dump

QueryParameters

collection(required):Thenameoridofthecollectiontodump.chunkSize(optional):Approximatemaximumsizeofthereturnedresult.batchId(required):rocksdbonly-Theidofthesnapshottousefrom(optional):mmfilesonly-Lowerboundtickvalueforresults.to(optional):mmfilesonly-Upperboundtickvalueforresults.includeSystem(optional):mmfilesonly-Includesystemcollectionsintheresult.Thedefaultvalueistrue.ticks(optional):mmfilesonly-Whetherornottoincludetickvaluesinthedump.Thedefaultvalueistrue.flush(optional):mmfilesonly-WhetherornottoflushtheWALbeforedumping.Thedefaultvalueistrue.

Returnsthedatafromthecollectionfortherequestedrange.

Whenthefromqueryparameterisnotused,collectioneventsarereturnedfromthebeginning.Whenthefromparameterisused,theresultwillonlycontaincollectionentrieswhichhavehighertickvaluesthanthespecifiedfromvalue(note:thelogentrywithatickvalueequaltofromwillbeexcluded).

Thetoqueryparametercanbeusedtooptionallyrestricttheupperboundoftheresulttoacertaintickvalue.Ifused,theresultwillonlycontaincollectionentrieswithtickvaluesupto(including)to.

ThechunkSizequeryparametercanbeusedtocontrolthesizeoftheresult.Itmustbespecifiedinbytes.ThechunkSizevaluewillonlybehonoredapproximately.OtherwiseatoolowchunkSizevaluecouldcausetheservertonotbeabletoputjustoneentryintotheresultandreturnit.Therefore,thechunkSizevaluewillonlybeconsultedafteranentryhasbeenwrittenintotheresult.IftheresultsizeisthenbiggerthanchunkSize,theserverwillrespondwithasmanyentriesasthereareintheresponsealready.IftheresultsizeisstillsmallerthanchunkSize,theserverwilltrytoreturnmoredataifthere'smoredatalefttoreturn.

IfchunkSizeisnotspecified,someserver-sidedefaultvaluewillbeused.

ReplicationDump

TheContent-Typeoftheresultisapplication/x-arango-dump.Thisisaneasy-to-processformat,withallentriesgoingontoseparatelinesintheresponsebody.

EachlineitselfisaJSONobject,withatleastthefollowingattributes:

tick:theoperation'stickattribute

key:thekeyofthedocument/edgeorthekeyusedinthedeletionoperation

rev:therevisionidofthedocument/edgeorthedeletionoperation

data:theactualdocument/edgedatafortypes2300and2301.Thefulldocument/edgedatawillbereturnedevenforupdates.

type:thetypeofentry.Possiblevaluesfortypeare:

2300:documentinsertion/update

2301:edgeinsertion/update

2302:document/edgedeletion

Note:therewillbenodistinctionbetweeninsertsandupdateswhencallingthismethod.

Example:Emptycollection:

shell>curl--dump-http://localhost:8529/_api/replication/dump?collection=testCollection

content-type:application/x-arango-dump;charset=utf-8

x-arango-replication-checkmore:false

x-arango-replication-lastincluded:0

Example:Non-emptycollection:

HTTP/1.1200OK

"{\"tick\":\"11980\",\"type\":2300,\"data\":{\"_id\":\"testCollection/123456\",\"_key\":\"123456\",\"_rev\":\"_WQ47bCW--D\",\"b

\":1,\"c\":false,\"d\":\"additionalvalue\"}}

{\"tick\":\"11984\",\"type\":2302,\"data\":{\"_key\":\"foobar\",\"_rev\":\"_WQ47bCa--B\"}}

{\"tick\":\"11986\",\"type\":2302,\"data\":{\"_key\":\"abcdef\",\"_rev\":\"_WQ47bCa--D\"}}

ReturnCodes

200:isreturnediftherequestwasexecutedsuccessfullyanddatawasreturned.Theheaderx-arango-replication-lastincludedissettothetickofthelastdocumentreturned.204:isreturnediftherequestwasexecutedsuccessfully,buttherewasnocontentavailable.Theheaderx-arango-replication-lastincludedis0inthiscase.400:isreturnedifeitherthefromortovaluesareinvalid.404:isreturnedwhenthecollectioncouldnotbefound.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.

ReplicationDump

Examples

Emptycollection:

Non-emptycollection:

HTTP/1.1200OK

"{\"tick\":\"11980\",\"type\":2300,\"data\":

{\"_id\":\"testCollection/123456\",\"_key\":\"123456\",\"_rev\":\"_WQ47bCW--

D\",\"b\":1,\"c\":false,\"d\":\"additional

value\"}}\n{\"tick\":\"11984\",\"type\":2302,\"data\":

{\"_key\":\"foobar\",\"_rev\":\"_WQ47bCa--

B\"}}\n{\"tick\":\"11986\",\"type\":2302,\"data\":

{\"_key\":\"abcdef\",\"_rev\":\"_WQ47bCa--D\"}}\n"

Synchronizedatafromaremoteendpoint

startareplication

PUT/_api/replication/sync

username:anoptionalArangoDBusernametousewhenconnectingtotheendpoint.includeSystem:whetherornotsystemcollectionoperationswillbeappliedendpoint:themasterendpointtoconnectto(e.g."tcp://192.168.173.13:8529").initialSyncMaxWaitTime:themaximumwaittime(inseconds)thattheinitialsynchronizationwillwaitforaresponsefromthemasterwhenfetchinginitialcollectiondata.Thiswaittimecanbeusedtocontrolafterwhattimetheinitialsynchronizationwillgiveupwaitingforaresponseandfail.Thisvaluewillbeignoredifsetto0.database:thedatabasenameonthemaster(ifnotspecified,defaultstothenameofthelocalcurrentdatabase).restrictType:anoptionalstringvalueforcollectionfiltering.Whenspecified,theallowedvaluesareincludeorexclude.incremental:ifsettotrue,thenanincrementalsynchronizationmethodwillbeusedforsynchronizingdataincollections.Thismethodisusefulwhencollectionsalreadyexistlocally,andonlytheremainingdifferencesneedtobetransferredfromtheremoteendpoint.Inthiscase,theincrementalsynchronizationcanbefasterthanafullsynchronization.Thedefaultvalueisfalse,meaningthatthecompletedatafromtheremotecollectionwillbetransferred.restrictCollections(string):anoptionalarrayofcollectionsforusewithrestrictType.IfrestrictTypeisinclude,onlythespecifiedcollectionswillbesychronised.IfrestrictTypeisexclude,allbutthespecifiedcollectionswillbesynchronized.password:thepasswordtousewhenconnectingtotheendpoint.

StartsafulldatasynchronizationfromaremoteendpointintothelocalArangoDBdatabase.

ReplicationDump

ThesyncmethodcanbeusedbyreplicationclientstoconnectanArangoDBdatabasetoaremoteendpoint,fetchtheremotelistofcollectionsandindexes,andcollectiondata.ItwillthuscreatealocalbackupofthestateofdataattheremoteArangoDBdatabase.syncworksonaper-databaselevel.

syncwillfirstfetchthelistofcollectionsandindexesfromtheremoteendpoint.ItdoessobycallingtheinventoryAPIoftheremotedatabase.ItwillthenpurgedatainthelocalArangoDBdatabase,andafterstartwilltransfercollectiondatafromtheremotedatabasetothelocalArangoDBdatabase.Itwillextractdatafromtheremotedatabasebycallingtheremotedatabase'sdumpAPIuntilalldataarefetched.

Incaseofsuccess,thebodyoftheresponseisaJSONobjectwiththefollowingattributes:

collections:anarrayofcollectionsthatweretransferredfromtheendpoint

lastLogTick:thelastlogtickontheendpointatthetimethetransferwasstarted.Usethisvalueasthefromvaluewhenstartingthecontinuoussynchronizationlater.

WARNING:callingthismethodwillsychronizedatafromthecollectionsfoundontheremoteendpointtothelocalArangoDBdatabase.Alldatainthelocalcollectionswillbepurgedandreplacedwithdatafromtheendpoint.

Usewithcaution!

Note:thismethodisnotsupportedonacoordinatorinacluster.

ReturnCodes

200:isreturnediftherequestwasexecutedsuccessfully.400:isreturnediftheconfigurationisincompleteormalformed.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredduringsychronization.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.

Returnclusterinventoryofcollectionsandindexes

retursanoverviewofcollectionsandindexesinacluster

GET/_api/replication/clusterInventory

QueryParameters

includeSystem(optional):Includesystemcollectionsintheresult.Thedefaultvalueistrue.

Returnsthearrayofcollectionsandindexesavailableonthecluster.

TheresponsewillbeanarrayofJSONobjects,oneforeachcollection.Eachcollectioncontainscontainsexactlytwokeys"parameters"and"indexes".ThisinformationcomesfromPlan/Collections/{DB-Name}/intheagency,justthattheindexes*attributethereisrelocatedtoadjustittothedataformatofarangodump.

ReturnCodes

ReplicationDump

ReplicationLoggerCommandsPreviousversionsofArangoDBallowedstarting,stoppingandconfiguringthereplicationlogger.ThesecommandsaresuperfluousinArangoDB2.2asalldata-modificationoperationsarewrittentotheserver'swrite-aheadlogandarenothandledbyaseparateloggeranymore.

TheonlyusefuloperationsremainingsinceArangoDB2.2aretoquerythecurrentstateoftheloggerandtofetchthelatestchangeswrittenbythelogger.Theoperationswillreturnthestateanddatafromthewrite-aheadlog.

Returnreplicationloggerstate

returnsthestateofthereplicationlogger

GET/_api/replication/logger-state

Returnsthecurrentstateoftheserver'sreplicationlogger.Thestatewillincludeinformationaboutwhethertheloggerisrunningandaboutthelastloggedtickvalue.Thistickvalueisimportantforincrementalfetchingofdata.

ThebodyoftheresponsecontainsaJSONobjectwiththefollowingattributes:

state:thecurrentloggerstateasaJSONobjectwiththefollowingsub-attributes:

running:whetherornottheloggerisrunning

lastLogTick:thetickvalueofthelatestticktheloggerhaslogged.Thisvaluecanbeusedforincrementalfetchingoflogdata.

totalEvents:totalnumberofeventsloggedsincetheserverwasstarted.Thevalueisnotresetbetweenmultiplestopsandre-startsofthelogger.

time:thecurrentdateandtimeontheloggerserver

server:aJSONobjectwiththefollowingsub-attributes:

version:theloggerserver'sversion

serverId:theloggerserver'sid

clients:returnsthelastfetchstatusbyreplicationclientsconnectedtothelogger.EachclientisreturnedasaJSONobjectwiththefollowingattributes:

serverId:serveridofclient

lastServedTick:lasttickvalueservedtothisclientviathelogger-followAPI

time:dateandtimewhenthisclientlastcalledthelogger-followAPI

Example:Returnsthestateofthereplicationlogger.

shell>curl--dump-http://localhost:8529/_api/replication/logger-state

HTTP/1.1200OK

"state":{

"running":true,

"totalEvents":4164,

"time":"2018-01-25T19:13:47Z"

"server":{

ReplicationLogger

"version":"3.3.3",

"serverId":"114837197342439"

"clients":[]

ReturnCodes

200:isreturnediftheloggerstatecouldbedeterminedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnediftheloggerstatecouldnotbedetermined.

Examples

Returnsthestateofthereplicationlogger.

shell>curl--dump-http://localhost:8529/_api/replication/logger-state

HTTP/1.1200OK

showresponsebodyToquerythelatestchangesloggedbythereplicationlogger,theHTTPinterfacealsoprovidesthelogger-followmethod.

ThismethodshouldbeusedbyreplicationclientstoincrementallyfetchupdatesfromanArangoDBdatabase.

Returnslogentries

Fetchloglinesfromtheserver

GET/_api/replication/logger-follow

QueryParameters

from(optional):Lowerboundtickvalueforresults.to(optional):Upperboundtickvalueforresults.chunkSize(optional):Approximatemaximumsizeofthereturnedresult.includeSystem(optional):Includesystemcollectionsintheresult.Thedefaultvalueistrue.

Returnsdatafromtheserver'sreplicationlog.Thismethodcanbecalledbyreplicationclientsafteraninitialsynchronizationofdata.Themethodwillreturnall"recent"logentriesfromtheloggerserver,andtheclientscanreplayandapplytheseentrieslocallysotheygettothesamedatastateastheloggerserver.

Clientscancallthismethodrepeatedlytoincrementallyfetchallchangesfromtheloggerserver.Inthiscase,theyshouldprovidethefromvaluesotheywillonlygetreturnedthelogeventssincetheirlastfetch.

Whenthefromqueryparameterisnotused,theloggerserverwillreturnlogentriesstartingatthebeginningofitsreplicationlog.Whenthefromparameterisused,theloggerserverwillonlyreturnlogentrieswhichhavehighertickvaluesthanthespecifiedfromvalue(note:thelogentrywithatickvalueequaltofromwillbeexcluded).Usethefromvaluewhenincrementallyfetchinglogdata.

Thetoqueryparametercanbeusedtooptionallyrestricttheupperboundoftheresulttoacertaintickvalue.Ifused,theresultwillcontainonlylogeventswithtickvaluesupto(including)to.Inincrementalfetching,thereisnoneedtousethetoparameter.Itonlymakessenseinspecialsituations,whenonlypartsofthechangelogarerequired.

ThechunkSizequeryparametercanbeusedtocontrolthesizeoftheresult.Itmustbespecifiedinbytes.ThechunkSizevaluewillonlybehonoredapproximately.OtherwiseatoolowchunkSizevaluecouldcausetheservertonotbeabletoputjustonelogentryintotheresultandreturnit.Therefore,thechunkSizevaluewillonlybeconsultedafteralogentryhasbeenwrittenintotheresult.IftheresultsizeisthenbiggerthanchunkSize,theserverwillrespondwithasmanylogentriesasthereareintheresponsealready.IftheresultsizeisstillsmallerthanchunkSize,theserverwilltrytoreturnmoredataifthere'smoredatalefttoreturn.

IfchunkSizeisnotspecified,someserver-sidedefaultvaluewillbeused.

ReplicationLogger

TheContent-Typeoftheresultisapplication/x-arango-dump.Thisisaneasy-to-processformat,withalllogeventsgoingontoseparatelinesintheresponsebody.EachlogeventitselfisaJSONobject,withatleastthefollowingattributes:

tick:thelogeventtickvalue

type:thelogeventtype

Individuallogeventswillalsohaveadditionalattributes,dependingontheeventtype.Afewcommonattributeswhichareusedformultipleeventstypesare:

cid:idofthecollectiontheeventwasfor

tid:idofthetransactiontheeventwascontainedin

key:documentkey

rev:documentrevisionid

data:theoriginaldocumentdata

Amoredetaileddescriptionoftheindividualreplicationeventtypesandtheirdatastructurescanbefoundinthemanual.

TheresponsewillalsocontainthefollowingHTTPheaders:

x-arango-replication-active:whetherornottheloggerisactive.Clientscanusethisflagasanindicationfortheirpollingfrequency.Iftheloggerisnotactiveandtherearenomorereplicationeventsavailable,itmightbesensibleforaclienttoabort,ortogotosleepforalongtimeandtryagainlatertocheckwhethertheloggerhasbeenactivated.

x-arango-replication-lastincluded:thetickvalueofthelastincludedvalueintheresult.Inincrementallogfetching,thisvaluecanbeusedasthefromvalueforthefollowingrequest.Notethatiftheresultisempty,thevaluewillbe0.Thisvalueshouldnotbeusedasfromvaluebyclientsinthenextrequest(otherwisetheserverwouldreturnthelogeventsfromthestartofthelogagain).

x-arango-replication-lasttick:thelasttickvaluetheloggerserverhaslogged(notnecessarilyincludedintheresult).Bycomparingthethelasttickandlastincludedtickvalues,clientshaveanapproximateindicationofhowmanyeventstherearestilllefttofetch.

x-arango-replication-checkmore:whetherornottherealreadyexistsmorelogdatawhichtheclientcouldfetchimmediately.Ifthereismorelogdataavailable,theclientcouldcalllogger-followagainwithanadjustedfromvaluetofetchremaininglogentriesuntiltherearenomore.

Ifthereisn'tanymorelogdatatofetch,theclientmightdecidetogotosleepforawhilebeforecallingtheloggeragain.

Example:Nologeventsavailable

shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?from=12070

x-arango-replication-frompresent:true

x-arango-replication-active:true

x-arango-replication-lasttick:12070

Example:Afewlogevents

ReplicationLogger

HTTP/1.1200OK

"{\"tick\":\"12072\",\"type\":2000,\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"allowUserKeys\":true

,\"cid\":\"12071\",\"count\":0,\"deleted\":false,\"doCompact\":true,\"globallyUniqueId\":\"h68719E5AC6E7/12071\",\"id\":\"12071

\",\"indexBuckets\":8,\"indexes\":[{\"fields\":[\"_key\"],\"id\":\"0\",\"selectivityEstimate\":1,\"sparse\":false,\"type\":\"pr

imary\",\"unique\":true}],\"isSmart\":false,\"isSystem\":false,\"isVolatile\":false,\"journalSize\":33554432,\"keyOptions\":{\"

allowUserKeys\":true,\"lastValue\":0,\"type\":\"traditional\"},\"name\":\"products\",\"numberOfShards\":1,\"planId\":\"12071\",

\"replicationFactor\":1,\"shardKeys\":[\"_key\"],\"shards\":{},\"status\":3,\"type\":2,\"version\":6,\"waitForSync\":false}}

{\"tick\":\"12076\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"_id\":\

"_unknown/p1\",\"_key\":\"p1\",\"_rev\":\"_WQ47eYu--_\",\"name\":\"fluxcompensator\"}}

"_unknown/p2\",\"_key\":\"p2\",\"_rev\":\"_WQ47eYu--B\",\"hp\":5100,\"name\":\"hybridhovercraft\"}}

{\"tick\":\"12080\",\"type\":2302,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"_key\":

\"p1\",\"_rev\":\"_WQ47eYu--D\"}}

"_unknown/p2\",\"_key\":\"p2\",\"_rev\":\"_WQ47eYy--_\",\"hp\":5100,\"name\":\"brokenhovercraft\"}}

{\"tick\":\"12083\",\"type\":2001,\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data\":{\"cuid\":\"h68719E5AC6E

7/12071\",\"id\":\"12071\",\"name\":\"products\"}}

{\"tick\":\"12086\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"cname\":\"_users\",\"data\":{\"_id\":\"_user

s/10695\",\"_key\":\"10695\",\"_rev\":\"_WQ47eY6--_\",\"authData\":{\"active\":false,\"simple\":{\"hash\":\"1b3c695816f896d7d52

522b6e7fac12b1da668981aa95710ae1ab36828df87f7\",\"salt\":\"aa6d4cfe\",\"method\":\"sha256\"}},\"databases\":{},\"source\":\"COL

LECTION\",\"user\":\"tester\",\"userData\":{}}}

s/89\",\"_key\":\"89\",\"_rev\":\"_WQ47eY6--B\",\"authData\":{\"active\":true,\"simple\":{\"hash\":\"90297fadeade5ffb0078e4f5aa

d32f22ab2180f11094b97794ac8a7326e2c30c\",\"salt\":\"a7522145\",\"method\":\"sha256\"}},\"databases\":{\"_system\":{\"permission

s\":{\"read\":true,\"write\":true},\"collections\":{\"*\":{\"permissions\":{\"read\":true,\"write\":true}}}},\"*\":{\"permissio

ns\":{\"read\":true,\"write\":true},\"collections\":{\"*\":{\"permissions\":{\"read\":true,\"write\":true}}}}},\"source\":\"COL

LECTION\",\"user\":\"root\"}}

s/10683\",\"_key\":\"10683\",\"_rev\":\"_WQ47eY6--D\",\"authData\":{\"active\":true,\"simple\":{\"hash\":\"bfff9a16dea55c4d6ec7

5b595684c76f0a020aa239c2fb7fc633b8a094289fbb\",\"salt\":\"6e4298cb\",\"method\":\"sha256\"}},\"databases\":{},\"source\":\"COLL

ECTION\",\"user\":\"admin\",\"userData\":{}}}

Example:Moreeventsthanwouldfitintotheresponse

shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?from=12050&chunkSize=400

HTTP/1.1200OK

x-arango-replication-checkmore:true

"{\"tick\":\"12052\",\"type\":2000,\"database\":\"1\",\"cid\":\"12051\",\"cname\":\"products\",\"data\":{\"allowUserKeys\":true

,\"cid\":\"12051\",\"count\":0,\"deleted\":false,\"doCompact\":true,\"globallyUniqueId\":\"h68719E5AC6E7/12051\",\"id\":\"12051

\",\"indexBuckets\":8,\"indexes\":[{\"fields\":[\"_key\"],\"id\":\"0\",\"selectivityEstimate\":1,\"sparse\":false,\"type\":\"pr

imary\",\"unique\":true}],\"isSmart\":false,\"isSystem\":false,\"isVolatile\":false,\"journalSize\":33554432,\"keyOptions\":{\"

allowUserKeys\":true,\"lastValue\":0,\"type\":\"traditional\"},\"name\":\"products\",\"numberOfShards\":1,\"planId\":\"12051\",

\"replicationFactor\":1,\"shardKeys\":[\"_key\"],\"shards\":{},\"status\":3,\"type\":2,\"version\":6,\"waitForSync\":false}}

ReturnCodes

200:isreturnediftherequestwasexecutedsuccessfully,andtherearelogeventsavailablefortherequestedrange.Theresponsebodywillnotbeemptyinthiscase.204:isreturnediftherequestwasexecutedsuccessfully,buttherearenologeventsavailablefortherequestedrange.Theresponsebodywillbeemptyinthiscase.

ReplicationLogger

400:isreturnedifeitherthefromortovaluesareinvalid.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.

Examples

Nologeventsavailable

Afewlogevents

HTTP/1.1200OK

{\"tick\":\"12072\",\"type\":2000,\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"product

s\",\"data\":

{\"allowUserKeys\":true,\"cid\":\"12071\",\"count\":0,\"deleted\":false,\"doCompact\":true

,\"globallyUniqueId\":\"h68719E5AC6E7/12071\",\"id\":\"12071\",\"indexBuckets\":8,\"indexe

s\":[{\"fields\":

[\"_key\"],\"id\":\"0\",\"selectivityEstimate\":1,\"sparse\":false,\"type\":\"primary\",\"

unique\":true}],\"isSmart\":false,\"isSystem\":false,\"isVolatile\":false,\"journalSize\":

33554432,\"keyOptions\":

{\"allowUserKeys\":true,\"lastValue\":0,\"type\":\"traditional\"},\"name\":\"products\",\"

numberOfShards\":1,\"planId\":\"12071\",\"replicationFactor\":1,\"shardKeys\":

[\"_key\"],\"shards\":

{},\"status\":3,\"type\":2,\"version\":6,\"waitForSync\":false}}\n{\"tick\":\"12076\",\"ty

pe\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\",\"cname\":\"products\",\"data

\":{\"_id\":\"_unknown/p1\",\"_key\":\"p1\",\"_rev\":\"_WQ47eYu--_\",\"name\":\"flux

compensator\"}}\n{\"tick\":\"12078\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\

":\"12071\",\"cname\":\"products\",\"data\":

{\"_id\":\"_unknown/p2\",\"_key\":\"p2\",\"_rev\":\"_WQ47eYu--

B\",\"hp\":5100,\"name\":\"hybrid

hovercraft\"}}\n{\"tick\":\"12080\",\"type\":2302,\"tid\":\"0\",\"database\":\"1\",\"cid\"

:\"12071\",\"cname\":\"products\",\"data\":{\"_key\":\"p1\",\"_rev\":\"_WQ47eYu--

D\"}}\n{\"tick\":\"12082\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"12071\

",\"cname\":\"products\",\"data\":

ReplicationLogger

{\"_id\":\"_unknown/p2\",\"_key\":\"p2\",\"_rev\":\"_WQ47eYy--

_\",\"hp\":5100,\"name\":\"broken

hovercraft\"}}\n{\"tick\":\"12083\",\"type\":2001,\"database\":\"1\",\"cid\":\"12071\",\"c

name\":\"products\",\"data\":

{\"cuid\":\"h68719E5AC6E7/12071\",\"id\":\"12071\",\"name\":\"products\"}}\n{\"tick\":\"12

086\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"cname\":\"_users\",\"

data\":{\"_id\":\"_users/10695\",\"_key\":\"10695\",\"_rev\":\"_WQ47eY6--_\",\"authData\":

{\"active\":false,\"simple\":

{\"hash\":\"1b3c695816f896d7d52522b6e7fac12b1da668981aa95710ae1ab36828df87f7\",\"salt\":\"

aa6d4cfe\",\"method\":\"sha256\"}},\"databases\":

{},\"source\":\"COLLECTION\",\"user\":\"tester\",\"userData\":

{}}}\n{\"tick\":\"12088\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"c

name\":\"_users\",\"data\":{\"_id\":\"_users/89\",\"_key\":\"89\",\"_rev\":\"_WQ47eY6--

B\",\"authData\":{\"active\":true,\"simple\":

{\"hash\":\"90297fadeade5ffb0078e4f5aad32f22ab2180f11094b97794ac8a7326e2c30c\",\"salt\":\"

a7522145\",\"method\":\"sha256\"}},\"databases\":{\"_system\":{\"permissions\":

{\"read\":true,\"write\":true},\"collections\":{\"*\":{\"permissions\":

{\"read\":true,\"write\":true}}}},\"*\":{\"permissions\":

{\"read\":true,\"write\":true},\"collections\":{\"*\":{\"permissions\":

{\"read\":true,\"write\":true}}}}},\"source\":\"COLLECTION\",\"user\":\"root\"}}\n{\"tick\

":\"12090\",\"type\":2300,\"tid\":\"0\",\"database\":\"1\",\"cid\":\"6\",\"cname\":\"_user

s\",\"data\":{\"_id\":\"_users/10683\",\"_key\":\"10683\",\"_rev\":\"_WQ47eY6--

D\",\"authData\":{\"active\":true,\"simple\":

{\"hash\":\"bfff9a16dea55c4d6ec75b595684c76f0a020aa239c2fb7fc633b8a094289fbb\",\"salt\":\"

6e4298cb\",\"method\":\"sha256\"}},\"databases\":

{},\"source\":\"COLLECTION\",\"user\":\"admin\",\"userData\":{}}}\n"

Moreeventsthanwouldfitintotheresponse

shell>curl--dump-http://localhost:8529/_api/replication/logger-follow?

from=12050&chunkSize=400

HTTP/1.1200OK

x-arango-replication-checkmore:true

{\"tick\":\"12052\",\"type\":2000,\"database\":\"1\",\"cid\":\"12051\",\"cname\":\"product

s\",\"data\":

{\"allowUserKeys\":true,\"cid\":\"12051\",\"count\":0,\"deleted\":false,\"doCompact\":true

,\"globallyUniqueId\":\"h68719E5AC6E7/12051\",\"id\":\"12051\",\"indexBuckets\":8,\"indexe

s\":[{\"fields\":

[\"_key\"],\"id\":\"0\",\"selectivityEstimate\":1,\"sparse\":false,\"type\":\"primary\",\"

unique\":true}],\"isSmart\":false,\"isSystem\":false,\"isVolatile\":false,\"journalSize\":

33554432,\"keyOptions\":

{\"allowUserKeys\":true,\"lastValue\":0,\"type\":\"traditional\"},\"name\":\"products\",\"

numberOfShards\":1,\"planId\":\"12051\",\"replicationFactor\":1,\"shardKeys\":

[\"_key\"],\"shards\":{},\"status\":3,\"type\":2,\"version\":6,\"waitForSync\":false}}\n"

ReplicationLogger

Tocheckwhatrangeofchangesisavailable(identifiedbytickvalues),theHTTPinterfaceprovidesthemethodslogger-first-tickandlogger-tick-ranges.Replicationclientscanusethemethodstodetermineifcertaindata(identifiedbyatickdate)isstillavailableonthemaster.

Returnsthefirstavailabletickvalue

Returnthefirstavailabletickvaluefromtheserver

GET/_api/replication/logger-first-tick

Returnsthefirstavailabletickvaluethatcanbeservedfromtheserver'sreplicationlog.Thismethodcanbecalledbyreplicationclientsaftertodetermineifcertaindata(identifiedbyatickvalue)isstillavailableforreplication.

TheresultisaJSONobjectcontainingtheattributefirstTick.Thisattributecontainstheminimumtickvalueavailableintheserver'sreplicationlog.

Example:Returningthefirstavailabletick

shell>curl--dump-http://localhost:8529/_api/replication/logger-first-tick

HTTP/1.1200OK

"{\"firstTick\":\"5\"}"

ReturnCodes

200:isreturnediftherequestwasexecutedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.

Examples

Returningthefirstavailabletick

shell>curl--dump-http://localhost:8529/_api/replication/logger-first-tick

HTTP/1.1200OK

"{\"firstTick\":\"5\"}"

ReturnthetickrangesavailableintheWALlogfiles

returnsthetickvaluerangesavailableinthelogfiles

GET/_api/replication/logger-tick-ranges

ReturnsthecurrentlyavailablerangesoftickvaluesforallcurrentlyavailableWALlogfiles.Thetickvaluescanbeusedtodetermineifcertaindata(identifiedbytickvalue)arestillavailableforreplication.

ThebodyoftheresponsecontainsaJSONarray.Eacharraymemberisanobjectthatdescribesasinglelogfile.Eachobjecthasthefollowingattributes:

datafile:nameofthelogfile

ReplicationLogger

status:statusofthedatafile,intextualform(e.g."sealed","open")

tickMin:minimumtickvaluecontainedinlogfile

tickMax:maximumtickvaluecontainedinlogfile

Example:Returnstheavailabletickranges.

shell>curl--dump-http://localhost:8529/_api/replication/logger-tick-ranges

HTTP/1.1200OK

"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-3.db",

"status":"collected",

"tickMin":"5",

"tickMax":"10381"

"tickMin":"10397",

"tickMax":"10483"

"tickMin":"10490",

"tickMax":"11986"

"tickMin":"11994",

"tickMax":"12003"

"status":"open",

"tickMin":"12009",

"tickMax":"12090"

ReturnCodes

200:isreturnedifthetickrangescouldbedeterminedsuccessfully.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnediftheloggerstatecouldnotbedetermined.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.

Examples

Returnstheavailabletickranges.

shell>curl--dump-http://localhost:8529/_api/replication/logger-tick-ranges

HTTP/1.1200OK

ReplicationLogger

"tickMin":"5",

"tickMax":"10381"

"tickMin":"10397",

"tickMax":"10483"

"tickMin":"10490",

"tickMax":"11986"

"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-

10384.db",

"tickMin":"11994",

"tickMax":"12003"

"datafile":"/tmp/arangosh_JqNjRy/tmp-26045-3007930411/data/journals/logfile-

10486.db",

"status":"open",

"tickMin":"12009",

"tickMax":"12090"

ReplicationLogger

ReplicationApplierCommandsTheappliercommandsallowtoremotelystart,stop,andquerythestateandconfigurationofanArangoDBdatabase'sreplicationapplier.

Returnconfigurationofreplicationapplier

fetchthecurrentreplicationconfiguration

GET/_api/replication/applier-config

Returnstheconfigurationofthereplicationapplier.

ThebodyoftheresponseisaJSONobjectwiththeconfiguration.Thefollowingattributesmaybepresentintheconfiguration:

endpoint:theloggerservertoconnectto(e.g."tcp://192.168.173.13:8529").

database:thenameofthedatabasetoconnectto(e.g."_system").

username:anoptionalArangoDBusernametousewhenconnectingtotheendpoint.

password:thepasswordtousewhenconnectingtotheendpoint.

maxConnectRetries:themaximumnumberofconnectionattemptstheapplierwillmakeinarow.Iftheappliercannotestablishaconnectiontotheendpointinthisnumberofattempts,itwillstopitself.

connectTimeout:thetimeout(inseconds)whenattemptingtoconnecttotheendpoint.Thisvalueisusedforeachconnectionattempt.

requestTimeout:thetimeout(inseconds)forindividualrequeststotheendpoint.

chunkSize:therequestedmaximumsizeforlogtransferpacketsthatisusedwhentheendpointiscontacted.

autoStart:whetherornottoauto-startthereplicationapplieron(nextandfollowing)serverstarts

adaptivePolling:whetherornotthereplicationapplierwilluseadaptivepolling.

includeSystem:whetherornotsystemcollectionoperationswillbeapplied

autoResync:whetherornottheslaveshouldperformafullautomaticresynchronizationwiththemasterincasethemastercannotservelogdatarequestedbytheslave,orwhenthereplicationisstartedandnotickvaluecanbefound.

autoResyncRetries:numberofresynchronizationretriesthatwillbeperformedinarowwhenautomaticresynchronizationisenabledandkicksin.Settingthisto0willeffectivelydisableautoResync.Settingittosomeothervaluewilllimitthenumberofretriesthatareperformed.Thishelpspreventingendlessretriesincaseresynchronizationsalwaysfail.

initialSyncMaxWaitTime:themaximumwaittime(inseconds)thattheinitialsynchronizationwillwaitforaresponsefromthemasterwhenfetchinginitialcollectiondata.Thiswaittimecanbeusedtocontrolafterwhattimetheinitialsynchronizationwillgiveupwaitingforaresponseandfail.ThisvalueisrelevantevenforcontinuousreplicationwhenautoResyncissettotruebecausethismayre-starttheinitialsynchronizationwhenthemastercannotprovidelogdatatheslaverequires.Thisvaluewillbeignoredifsetto0.

connectionRetryWaitTime:thetime(inseconds)thattheapplierwillintentionallyidlebeforeitretriesconnectingtothemasterincaseofconnectionproblems.Thisvaluewillbeignoredifsetto0.

idleMinWaitTime:theminimumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdata.ThiswaittimecanbeusedtocontrolthefrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemaster.Thisvaluewillbeignoredifsetto0.

idleMaxWaitTime:themaximumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdataandtherehavebeenpreviouslogfetchattemptsthatresultedinnomorelogdata.ThiswaittimecanbeusedtocontrolthemaximumfrequencywithwhichthereplicationappliersendsHTTPlogfetch

ReplicationApplier

requeststothemasterincasethereisnowriteactivityonthemasterforlongerperiods.ThisconfigurationvaluewillonlybeusediftheoptionadaptivePollingissettotrue.Thisvaluewillbeignoredifsetto0.

requireFromPresent:ifsettotrue,thenthereplicationapplierwillcheckatstartwhetherthestarttickfromwhichitstartsorresumesreplicationisstillpresentonthemaster.Ifnot,thentherewouldbedataloss.IfrequireFromPresentistrue,thereplicationapplierwillabortwithanappropriateerrormessage.Ifsettofalse,thenthereplicationapplierwillstillstart,andignorethedataloss.

verbose:ifsettotrue,thenaloglinewillbeemittedforalloperationsperformedbythereplicationapplier.Thisshouldbeusedfordebuggingreplicationproblemsonly.

restrictType:theconfigurationforrestrictCollections

restrictCollections:theoptionalarrayofcollectionstoincludeorexclude,basedonthesettingofrestrictType

Example:

shell>curl--dump-http://localhost:8529/_api/replication/applier-config

HTTP/1.1200OK

"requestTimeout":600,

"connectTimeout":10,

"ignoreErrors":0,

"maxConnectRetries":100,

"lockTimeoutRetries":0,

"sslProtocol":0,

"chunkSize":0,

"skipCreateDrop":false,

"autoStart":false,

"adaptivePolling":true,

"autoResync":false,

"autoResyncRetries":2,

"includeSystem":true,

"requireFromPresent":false,

"verbose":false,

"incremental":false,

"restrictType":"",

"restrictCollections":[],

"connectionRetryWaitTime":15,

"initialSyncMaxWaitTime":300,

"idleMinWaitTime":1,

"idleMaxWaitTime":2.5,

"force32mode":false

ReturnCodes

Examples

shell>curl--dump-http://localhost:8529/_api/replication/applier-config

HTTP/1.1200OK

showresponsebody

ReplicationApplier

Adjustconfigurationofreplicationapplier

setconfigurationvaluesofanapplier

PUT/_api/replication/applier-config

username:anoptionalArangoDBusernametousewhenconnectingtotheendpoint.includeSystem:whetherornotsystemcollectionoperationswillbeappliedendpoint:theloggerservertoconnectto(e.g."tcp://192.168.173.13:8529").Theendpointmustbespecified.verbose:ifsettotrue,thenaloglinewillbeemittedforalloperationsperformedbythereplicationapplier.Thisshouldbeusedfordebuggingreplicationproblemsonly.connectTimeout:thetimeout(inseconds)whenattemptingtoconnecttotheendpoint.Thisvalueisusedforeachconnectionattempt.autoResync:whetherornottheslaveshouldperformafullautomaticresynchronizationwiththemasterincasethemastercannotservelogdatarequestedbytheslave,orwhenthereplicationisstartedandnotickvaluecanbefound.database:thenameofthedatabaseontheendpoint.Ifnotspecified,defaultstothecurrentlocaldatabasename.idleMinWaitTime:theminimumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdata.ThiswaittimecanbeusedtocontrolthefrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemaster.Thisvaluewillbeignoredifsetto0.requestTimeout:thetimeout(inseconds)forindividualrequeststotheendpoint.requireFromPresent:ifsettotrue,thenthereplicationapplierwillcheckatstartwhetherthestarttickfromwhichitstartsorresumesreplicationisstillpresentonthemaster.Ifnot,thentherewouldbedataloss.IfrequireFromPresentistrue,thereplicationapplierwillabortwithanappropriateerrormessage.Ifsettofalse,thenthereplicationapplierwillstillstart,andignorethedataloss.idleMaxWaitTime:themaximumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdataandtherehavebeenpreviouslogfetchattemptsthatresultedinnomorelogdata.ThiswaittimecanbeusedtocontrolthemaximumfrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemasterforlongerperiods.ThisconfigurationvaluewillonlybeusediftheoptionadaptivePollingissettotrue.Thisvaluewillbeignoredifsetto0.restrictCollections(string):thearrayofcollectionstoincludeorexclude,basedonthesettingofrestrictTyperestrictType:theconfigurationforrestrictCollections;HastobeeitherincludeorexcludeinitialSyncMaxWaitTime:themaximumwaittime(inseconds)thattheinitialsynchronizationwillwaitforaresponsefromthemasterwhenfetchinginitialcollectiondata.Thiswaittimecanbeusedtocontrolafterwhattimetheinitialsynchronizationwillgiveupwaitingforaresponseandfail.ThisvalueisrelevantevenforcontinuousreplicationwhenautoResyncissettotruebecausethismayre-starttheinitialsynchronizationwhenthemastercannotprovidelogdatatheslaverequires.Thisvaluewillbeignoredifsetto0.maxConnectRetries:themaximumnumberofconnectionattemptstheapplierwillmakeinarow.Iftheappliercannotestablishaconnectiontotheendpointinthisnumberofattempts,itwillstopitself.autoStart:whetherornottoauto-startthereplicationapplieron(nextandfollowing)serverstartsadaptivePolling:ifsettotrue,thereplicationapplierwillfalltosleepforanincreasinglylongperiodincasetheloggerserverattheendpointdoesnothaveanymorereplicationeventstoapply.Usingadaptivepollingisthususefultoreducetheamountofworkforboththeapplierandtheloggerserverforcaseswhenthereareonlyinfrequentchanges.Thedownsideisthatwhenusingadaptivepolling,itmighttakelongerforthereplicationappliertodetectthattherearenewreplicationeventsontheloggerserver.SettingadaptivePollingtofalsewillmakethereplicationappliercontacttheloggerserverinaconstantinterval,regardlessofwhethertheloggerserverprovidesupdatesfrequentlyorseldom.password:thepasswordtousewhenconnectingtotheendpoint.connectionRetryWaitTime:thetime(inseconds)thattheapplierwillintentionallyidlebeforeitretriesconnectingtothemasterincaseofconnectionproblems.Thisvaluewillbeignoredifsetto0.autoResyncRetries:numberofresynchronizationretriesthatwillbeperformedinarowwhenautomaticresynchronizationisenabledandkicksin.Settingthisto0willeffectivelydisableautoResync.Settingittosomeothervaluewilllimitthenumberofretriesthatareperformed.Thishelpspreventingendlessretriesincaseresynchronizationsalwaysfail.chunkSize:therequestedmaximumsizeforlogtransferpacketsthatisusedwhentheendpointiscontacted.

Setstheconfigurationofthereplicationapplier.Theconfigurationcanonlybechangedwhiletheapplierisnotrunning.Theupdatedconfigurationwillbesavedimmediatelybutonlybecomeactivewiththenextstartoftheapplier.

ReplicationApplier

Incaseofsuccess,thebodyoftheresponseisaJSONobjectwiththeupdatedconfiguration.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/replication/applier-config<<EOF

"endpoint":"tcp://127.0.0.1:8529",

"username":"replicationApplier",

"password":"applier1234@foxx",

"chunkSize":4194304,

"autoStart":false,

"adaptivePolling":true

HTTP/1.1200OK

"endpoint":"tcp://127.0.0.1:8529",

"requestTimeout":600,

"connectTimeout":10,

"ignoreErrors":0,

"maxConnectRetries":100,

"lockTimeoutRetries":0,

"sslProtocol":0,

"skipCreateDrop":false,

"autoStart":false,

"adaptivePolling":true,

"autoResync":false,

"autoResyncRetries":2,

"includeSystem":true,

"requireFromPresent":false,

"verbose":false,

"incremental":false,

"restrictType":"",

"restrictCollections":[],

"connectionRetryWaitTime":15,

"initialSyncMaxWaitTime":300,

"idleMinWaitTime":1,

"idleMaxWaitTime":2.5,

"force32mode":false

ReturnCodes

200:isreturnediftherequestwasexecutedsuccessfully.400:isreturnediftheconfigurationisincompleteormalformed,orifthereplicationapplieriscurrentlyrunning.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.

Examples

http://localhost:8529/_api/replication/applier-config<<EOF

"endpoint":"tcp://127.0.0.1:8529",

"password":"applier1234@foxx",

"autoStart":false,

"adaptivePolling":true

ReplicationApplier

HTTP/1.1200OK

showresponsebody

Startreplicationapplier

startthereplicationapplier

PUT/_api/replication/applier-start

QueryParameters

from(optional):TheremotelastLogTickvaluefromwhichtostartapplying.Ifnotspecified,thelastsavedtickfromthepreviousapplierrunisused.Ifthereisnopreviousapplierstatesaved,theapplierwillstartatthebeginningoftheloggerserver'slog.

Startsthereplicationapplier.Thiswillreturnimmediatelyifthereplicationapplierisalreadyrunning.

Ifthereplicationapplierisnotalreadyrunning,theapplierconfigurationwillbechecked,andifitiscomplete,theapplierwillbestartedinabackgroundthread.Thismeansthateveniftheapplierwillencounteranyerrorswhilerunning,theywillnotbereportedintheresponsetothismethod.

Todetectreplicationappliererrorsaftertheapplierwasstarted,usethe/_api/replication/applier-stateAPIinstead.

Example:

shell>curl-XPUT--dump-http://localhost:8529/_api/replication/applier-start

HTTP/1.1200OK

"state":{

"running":true,

"lastAppliedContinuousTick":null,

"lastProcessedContinuousTick":null,

"lastAvailableContinuousTick":null,

"safeResumeTick":null,

"progress":{

"time":"2018-01-25T19:13:18Z",

"message":"applierinitiallycreatedfordatabase'_system'",

"failedConnects":0

"totalRequests":0,

"totalFailedConnects":0,

"totalEvents":0,

"totalResyncs":0,

"totalOperationsExcluded":0,

"lastError":{

"errorNum":0

"time":"2018-01-25T19:13:41Z"

"server":{

"version":"3.3.3",

"serverId":"114837197342439"

"endpoint":"tcp://127.0.0.1:8529",

"database":"_system"

ReplicationApplier

ReturnCodes

200:isreturnediftherequestwasexecutedsuccessfully.400:isreturnedifthereplicationapplierisnotfullyconfiguredortheconfigurationisinvalid.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredwhileassemblingtheresponse.

Examples

shell>curl-XPUT--dump-http://localhost:8529/_api/replication/applier-start

HTTP/1.1200OK

showresponsebody

Stopreplicationapplier

stopthereplication

PUT/_api/replication/applier-stop

Stopsthereplicationapplier.Thiswillreturnimmediatelyifthereplicationapplierisnotrunning.

Example:

shell>curl-XPUT--dump-http://localhost:8529/_api/replication/applier-stop

HTTP/1.1200OK

"state":{

"running":false,

"progress":{

"time":"2018-01-25T19:13:43Z",

"message":"appliershutdown",

"failedConnects":0

"totalRequests":6,

"totalEvents":0,

"totalResyncs":0,

"lastError":{

"errorNum":0

"time":"2018-01-25T19:13:43Z"

"server":{

"version":"3.3.3",

"serverId":"114837197342439"

"endpoint":"tcp://127.0.0.1:8529",

ReturnCodes

ReplicationApplier

Examples

shell>curl-XPUT--dump-http://localhost:8529/_api/replication/applier-stop

HTTP/1.1200OK

showresponsebody

Stateofthereplicationapplier

outputthecurrentstatusofthereplication

GET/_api/replication/applier-state

Returnsthestateofthereplicationapplier,regardlessofwhethertheapplieriscurrentlyrunningornot.

state:aJSONobjectwiththefollowingsub-attributes:

running:whetherornottheapplierisactiveandrunning

lastAppliedContinuousTick:thelasttickvaluefromthecontinuousreplicationlogtheapplierhasapplied.

lastProcessedContinuousTick:thelasttickvaluefromthecontinuousreplicationlogtheapplierhasprocessed.

Regularly,thelastappliedandlastprocessedtickvaluesshouldbeidentical.Fortransactionaloperations,thereplicationapplierwillfirstprocessincominglogeventsbeforeapplyingthem,sotheprocessedtickvaluemightbehigherthantheappliedtickvalue.Thiswillbethecaseuntiltheapplierencountersthetransactioncommitlogeventforthetransaction.

lastAvailableContinuousTick:thelasttickvaluetheloggerservercanprovide.

time:thetimeontheapplierserver.

totalRequests:thetotalnumberofrequeststheapplierhasmadetotheendpoint.

totalFailedConnects:thetotalnumberoffailedconnectionattemptstheapplierhasmade.

totalEvents:thetotalnumberoflogeventstheapplierhasprocessed.

totalOperationsExcluded:thetotalnumberoflogeventsexcludedbecauseofrestrictCollections.

progress:aJSONobjectwithdetailsaboutthereplicationapplierprogress.Itcontainsthefollowingsub-attributesifthereisprogresstoreport:

message:atextualdescriptionoftheprogress

time:thedateandtimetheprogresswaslogged

failedConnects:thecurrentnumberoffailedconnectionattempts

lastError:aJSONobjectwithdetailsaboutthelasterrorthathappenedontheapplier.Itcontainsthefollowingsub-attributesiftherewasanerror:

errorNum:anumericalerrorcode

errorMessage:atextualerrordescription

time:thedateandtimetheerroroccurred

Incasenoerrorhasoccurred,lastErrorwillbeempty.

ReplicationApplier

version:theapplierserver'sversion

serverId:theapplierserver'sid

endpoint:theendpointtheapplierisconnectedto(ifapplierisactive)orwillconnectto(ifapplieriscurrentlyinactive)

database:thenameofthedatabasetheapplierisconnectedto(ifapplierisactive)orwillconnectto(ifapplieriscurrentlyinactive)

Example:Fetchingthestateofaninactiveapplier:

shell>curl--dump-http://localhost:8529/_api/replication/applier-state

HTTP/1.1200OK

"state":{

"running":false,

"progress":{

"time":"2018-01-25T19:13:42Z",

"message":"appliershutdown",

"failedConnects":1

"totalRequests":2,

"totalEvents":0,

"totalResyncs":0,

"lastError":{

"errorNum":0

"time":"2018-01-25T19:13:42Z"

"server":{

"version":"3.3.3",

"serverId":"114837197342439"

"endpoint":"tcp://127.0.0.1:8529",

Example:Fetchingthestateofanactiveapplier:

HTTP/1.1200OK

"state":{

"running":true,

"progress":{

ReplicationApplier

"time":"2018-01-25T19:13:42Z",

"message":"fetchingmasterstateinformation",

"failedConnects":0

"totalRequests":2,

"totalEvents":0,

"totalResyncs":0,

"lastError":{

"errorNum":0

"time":"2018-01-25T19:13:42Z"

"server":{

"version":"3.3.3",

"serverId":"114837197342439"

"endpoint":"tcp://127.0.0.1:8529",

ReturnCodes

Examples

Fetchingthestateofaninactiveapplier:

HTTP/1.1200OK

showresponsebodyFetchingthestateofanactiveapplier:

HTTP/1.1200OK

showresponsebody

Turntheserverintoaslaveofanother

Changesroletoslave

PUT/_api/replication/make-slave

username:anoptionalArangoDBusernametousewhenconnectingtothemaster.includeSystem:whetherornotsystemcollectionoperationswillbeappliedendpoint:themasterendpointtoconnectto(e.g."tcp://192.168.173.13:8529").verbose:ifsettotrue,thenaloglinewillbeemittedforalloperationsperformedbythereplicationapplier.Thisshouldbeusedfordebuggingreplicationproblemsonly.

ReplicationApplier

connectTimeout:thetimeout(inseconds)whenattemptingtoconnecttotheendpoint.Thisvalueisusedforeachconnectionattempt.autoResync:whetherornottheslaveshouldperformanautomaticresynchronizationwiththemasterincasethemastercannotservelogdatarequestedbytheslave,orwhenthereplicationisstartedandnotickvaluecanbefound.database:thedatabasenameonthemaster(ifnotspecified,defaultstothenameofthelocalcurrentdatabase).idleMinWaitTime:theminimumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdata.ThiswaittimecanbeusedtocontrolthefrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemaster.Thisvaluewillbeignoredifsetto0.requestTimeout:thetimeout(inseconds)forindividualrequeststotheendpoint.restrictType:anoptionalstringvalueforcollectionfiltering.Whenspecified,theallowedvaluesareincludeorexclude.idleMaxWaitTime:themaximumwaittime(inseconds)thattheapplierwillintentionallyidlebeforefetchingmorelogdatafromthemasterincasethemasterhasalreadysentallitslogdataandtherehavebeenpreviouslogfetchattemptsthatresultedinnomorelogdata.ThiswaittimecanbeusedtocontrolthemaximumfrequencywithwhichthereplicationappliersendsHTTPlogfetchrequeststothemasterincasethereisnowriteactivityonthemasterforlongerperiods.ThisconfigurationvaluewillonlybeusediftheoptionadaptivePollingissettotrue.Thisvaluewillbeignoredifsetto0.initialSyncMaxWaitTime:themaximumwaittime(inseconds)thattheinitialsynchronizationwillwaitforaresponsefromthemasterwhenfetchinginitialcollectiondata.Thiswaittimecanbeusedtocontrolafterwhattimetheinitialsynchronizationwillgiveupwaitingforaresponseandfail.ThisvalueisrelevantevenforcontinuousreplicationwhenautoResyncissettotruebecausethismayre-starttheinitialsynchronizationwhenthemastercannotprovidelogdatatheslaverequires.Thisvaluewillbeignoredifsetto0.restrictCollections(string):anoptionalarrayofcollectionsforusewithrestrictType.IfrestrictTypeisinclude,onlythespecifiedcollectionswillbesychronised.IfrestrictTypeisexclude,allbutthespecifiedcollectionswillbesynchronized.requireFromPresent:ifsettotrue,thenthereplicationapplierwillcheckatstartofitscontinuousreplicationifthestarttickfromthedumpphaseisstillpresentonthemaster.Ifnot,thentherewouldbedataloss.IfrequireFromPresentistrue,thereplicationapplierwillabortwithanappropriateerrormessage.Ifsettofalse,thenthereplicationapplierwillstillstart,andignorethedataloss.adaptivePolling:whetherornotthereplicationapplierwilluseadaptivepolling.maxConnectRetries:themaximumnumberofconnectionattemptstheapplierwillmakeinarow.Iftheappliercannotestablishaconnectiontotheendpointinthisnumberofattempts,itwillstopitself.password:thepasswordtousewhenconnectingtothemaster.connectionRetryWaitTime:thetime(inseconds)thattheapplierwillintentionallyidlebeforeitretriesconnectingtothemasterincaseofconnectionproblems.Thisvaluewillbeignoredifsetto0.autoResyncRetries:numberofresynchronizationretriesthatwillbeperformedinarowwhenautomaticresynchronizationisenabledandkicksin.Settingthisto0willeffectivelydisableautoResync.Settingittosomeothervaluewilllimitthenumberofretriesthatareperformed.Thishelpspreventingendlessretriesincaseresynchronizationsalwaysfail.chunkSize:therequestedmaximumsizeforlogtransferpacketsthatisusedwhentheendpointiscontacted.

StartsafulldatasynchronizationfromaremoteendpointintothelocalArangoDBdatabaseandafterwardsstartsthecontinuousreplication.Theoperationworksonaper-databaselevel.

Alllocaldatabasedatawillberemovedpriortothesynchronization.

Incaseofsuccess,thebodyoftheresponseisaJSONobjectwiththefollowingattributes:

state:aJSONobjectwiththefollowingsub-attributes:

running:whetherornottheapplierisactiveandrunning

lastAppliedContinuousTick:thelasttickvaluefromthecontinuousreplicationlogtheapplierhasapplied.

lastProcessedContinuousTick:thelasttickvaluefromthecontinuousreplicationlogtheapplierhasprocessed.

Regularly,thelastappliedandlastprocessedtickvaluesshouldbeidentical.Fortransactionaloperations,thereplicationapplierwillfirstprocessincominglogeventsbeforeapplyingthem,sotheprocessedtickvaluemightbehigherthantheappliedtickvalue.Thiswillbethecaseuntiltheapplierencountersthetransactioncommitlogeventforthetransaction.

lastAvailableContinuousTick:thelasttickvaluetheloggerservercanprovide.

time:thetimeontheapplierserver.

ReplicationApplier

totalRequests:thetotalnumberofrequeststheapplierhasmadetotheendpoint.

totalFailedConnects:thetotalnumberoffailedconnectionattemptstheapplierhasmade.

totalEvents:thetotalnumberoflogeventstheapplierhasprocessed.

totalOperationsExcluded:thetotalnumberoflogeventsexcludedbecauseofrestrictCollections.

progress:aJSONobjectwithdetailsaboutthereplicationapplierprogress.Itcontainsthefollowingsub-attributesifthereisprogresstoreport:

message:atextualdescriptionoftheprogress

time:thedateandtimetheprogresswaslogged

failedConnects:thecurrentnumberoffailedconnectionattempts

lastError:aJSONobjectwithdetailsaboutthelasterrorthathappenedontheapplier.Itcontainsthefollowingsub-attributesiftherewasanerror:

errorNum:anumericalerrorcode

errorMessage:atextualerrordescription

time:thedateandtimetheerroroccurred

Incasenoerrorhasoccurred,lastErrorwillbeempty.

version:theapplierserver'sversion

serverId:theapplierserver'sid

endpoint:theendpointtheapplierisconnectedto(ifapplierisactive)orwillconnectto(ifapplieriscurrentlyinactive)

database:thenameofthedatabasetheapplierisconnectedto(ifapplierisactive)orwillconnectto(ifapplieriscurrentlyinactive)

WARNING:callingthismethodwillsychronizedatafromthecollectionsfoundontheremotemastertothelocalArangoDBdatabase.Alldatainthelocalcollectionswillbepurgedandreplacedwithdatafromthemaster.

Usewithcaution!

Pleasealsokeepinmindthatthiscommandmaytakealongtimetocompleteandreturn.Thisisbecauseitwillfirstdoafulldatasynchronizationwiththemaster,whichwilltaketimeroughlyproportionaltotheamountofdata.

ReturnCodes

200:isreturnediftherequestwasexecutedsuccessfully.400:isreturnediftheconfigurationisincompleteormalformed.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnedifanerroroccurredduringsychronizationorwhenstartingthecontinuousreplication.501:isreturnedwhenthisoperationiscalledonacoordinatorinacluster.

ReplicationApplier

Returnserverid

fetchthisserver'suniqueidentifier

GET/_api/replication/server-id

Returnstheserversid.TheidisalsoreturnedbyotherreplicationAPImethods,andthismethodisaneasymeansofdeterminingaserver'sid.

ThebodyoftheresponseisaJSONobjectwiththeattributeserverId.Theserveridisreturnedasastring.

Example:

shell>curl--dump-http://localhost:8529/_api/replication/server-id

HTTP/1.1200OK

"serverId":"114837197342439"

ReturnCodes

Examples

shell>curl--dump-http://localhost:8529/_api/replication/server-id

HTTP/1.1200OK

"serverId":"114837197342439"

HTTPInterfaceforShardingShardingonlyshouldbeusedbydevelopers!

Executeclusterroundtrip

executesaclusterroundtripforsharding

GET/_admin/cluster-test

ExecutesaclusterroundtripfromacoordinatortoaDBserverandback.Thiscallonlyworksinacoordinatornodeinacluster.OnecanandshouldappendanarbitrarypathtotheURLandthepartafter/_admin/cluster-testisusedasthepathoftheHTTPrequestwhichissentfromthecoordinatortoaDBnode.Likewise,anyformdataappendedtotheURLisforwardedintherequesttotheDBnode.Thishandlertakescareofallrequesttypes(seebelow)andusesthesamerequesttypeinitsrequesttotheDBnode.

ThefollowingHTTPheadersareinterpretedinaspecialway:

X-Shard-ID:ThisspecifiestheIDoftheshardtowhichtheclusterrequestissentandthustellsthesystemtowhichDBservertosendtheclusterrequest.NotethatthemappingfromtheshardIDtotheresponsibleserverhastobedefinedintheagencyunderCurrent/ShardLocation/.Onehastogivethisheader,otherwisethesystemdoesnotknowwheretosendtherequest.X-Client-Transaction-ID:thevalueofthisheaderistakenastheclienttransactionIDfortherequestX-Timeout:specifiesatimeoutinsecondsfortheclusteroperation.Iftheanswerdoesnotarrivewithinthespecifiedtimeout,ancorrespondingerrorisreturnedandanysubsequentrealanswerisignored.Thedefaultifnotgivenis24hours.X-Synchronous-Mode:Ifsettotruethetestfunctionusessynchronousmode,otherwisethedefaultasynchronousoperationmodeisused.Thisismainlyfordebuggingpurposes.Host:ThisheaderisignoredandnotforwardedtotheDBserver.User-Agent:ThisheaderisignoredandnotforwardedtotheDBserver.

AllotherHTTPheadersandthebodyoftherequest(ifpresent,seeotherHTTPmethodsbelow)areforwardedasgivenintheoriginalrequest.

InasynchronousmodetheDBserveranswerswithanHTTPrequestofitsown,insynchronousmodeitsendsaHTTPresponse.InbothcasestheheadersandthebodyareusedtoproducetheHTTPresponseofthisAPIcall.

ReturnCodes

Thereturncodecanbeanythingtheclusterrequestreturns,aswellas:

200:isreturnedwheneverythingwentwell,orifatimeoutoccurred.Inthelattercaseabodyoftypeapplication/jsonindicatingthetimeoutisreturned.403:isreturnedifArangoDBisnotrunninginclustermode.404:isreturnedifArangoDBwasnotcompiledforclusteroperation.

POST/_admin/cluster-test

Thebodycanbeanytypeandissimplyforwarded.

SeeGETmethod.

PUT/_admin/cluster-test

Sharding

SeeGETmethod.Thebodycanbeanytypeandissimplyforwarded.

Deleteclusterroundtrip

DELETE/_admin/cluster-test

SeeGETmethod.

Updateclusterroundtrip

PATCH/_admin/cluster-test

SeeGETmethod.Thebodycanbeanytypeandissimplyforwarded.

HEAD/_admin/cluster-test

SeeGETmethod.

Checkport

allowstocheckwhetheragivenportisusable

GET/_admin/clusterCheckPort

QueryParameters

port(required):

ReturnCodes

200:isreturnedwheneverythingwentwell.400:theparameterportwasnotgivenorisnointeger.

Sharding

HTTPInterfaceforAdministrationandMonitoringThisisanintroductiontoArangoDB'sHTTPinterfaceforadministrationandmonitoringoftheserver.

Readgloballogsfromtheserver

returnstheserverlogs

GET/_admin/log

QueryParameters

upto(optional):Returnsalllogentriesuptologlevelupto.Notethatuptomustbe:fatalor0erroror1warningor2infoor3debugor4Thedefaultvalueisinfo.level(optional):Returnsalllogentriesofloglevellevel.Notethatthequeryparametersuptoandlevelaremutuallyexclusive.start(optional):Returnsalllogentriessuchthattheirlogentryidentifier(lidvalue)isgreaterorequaltostart.size(optional):Restrictstheresulttoatmostsizelogentries.offset(optional):Startstoreturnlogentriesskippingthefirstoffsetlogentries.offsetandsizecanbeusedforpagination.search(optional):Onlyreturnthelogentriescontainingthetextspecifiedinsearch.sort(optional):Sortthelogentrieseitherascending(ifsortisasc)ordescending(ifsortisdesc)accordingtotheirlidvalues.Notethatthelidimposesachronologicalorder.Thedefaultvalueisasc.

Returnsfatal,error,warningorinfologmessagesfromtheserver'sgloballog.TheresultisaJSONobjectwiththefollowingattributes:

HTTP200

lid(string):alistoflogentryidentifiers.Eachlogmessageisuniquelyidentifiedbyits@LIT{lid}andtheidentifiersareinascendingorder.level:Alistoftheloglevelsforalllogentries.timestamp(string):alistofthetimestampsassecondssince1970-01-01foralllogentries.topic:alistofthetopicsofalllogentriestext:alistofthetextsofalllogentriestotalAmount:thetotalamountoflogentriesbeforepagination.

ReturnCodes

ResponseBody

lid(string):alistoflogentryidentifiers.Eachlogmessageisuniquelyidentifiedbyits@LIT{lid}andtheidentifiersareinascendingorder.-level:Alistoftheloglevelsforalllogentries.text:alistofthetextsofalllogentriestopic:alistofthetopicsofalllogentriestimestamp(string):alistofthetimestampsassecondssince1970-01-01foralllogentries.-totalAmount:thetotalamountoflogentriesbeforepagination.

Returnthecurrentserverloglevel

returnsthecurrentloglevelsettings

GET/_admin/log/level

Monitoring

Returnstheserver'scurrentloglevelsettings.TheresultisaJSONobjectwiththelogtopicsbeingtheobjectkeys,andtheloglevelsbeingtheobjectvalues.

ReturnCodes

200:isreturnediftherequestisvalid500:isreturnediftheservercannotgeneratetheresultduetoanout-of-memoryerror.

Modifyandreturnthecurrentserverloglevel

modifiesthecurrentloglevelsettings

PUT/_admin/log/level

Modifiesandreturnstheserver'scurrentloglevelsettings.TherequestbodymustbeaJSONobjectwiththelogtopicsbeingtheobjectkeysandtheloglevelsbeingtheobjectvalues.

TheresultisaJSONobjectwiththeadjustedlogtopicsbeingtheobjectkeys,andtheadjustedloglevelsbeingtheobjectvalues.

Itcansettheloglevelofallfacilitiesbyonlyspecifyingtheloglevelasstringwithoutjson.

Possibleloglevelsare:

FATAL-Therewillbenowayoutofthis.ArangoDBwillgodownafterthismessage.ERROR-Thisisanerror.youshouldinvestigateandfixit.Itmayharmyourproduction.WARNING-Thismaybeseriousapplication-wise,butwedon'tknow.INFO-Somethinghashappened,takenotice,butnodramaattached.DEBUG-outputdebugmessagesTRACE-trace-prepareyourlogtobeflooded-don'tuseinproduction.

audit-service:Oneofthepossibleloglevels.cache:Oneofthepossibleloglevels.syscall:Oneofthepossibleloglevels.communication:Oneofthepossibleloglevels.audit-authentication:Oneofthepossibleloglevels.agencycomm:Oneofthepossibleloglevels.startup:Oneofthepossibleloglevels.general:Oneofthepossibleloglevels.cluster:Oneofthepossibleloglevels.audit-view:Oneofthepossibleloglevels.collector:Oneofthepossibleloglevels.audit-documentation:Oneofthepossibleloglevels.engines:Oneofthepossibleloglevels.trx:Oneofthepossibleloglevels.mmap:Oneofthepossibleloglevels.agency:Oneofthepossibleloglevels.authentication:Oneofthepossibleloglevels.memory:Oneofthepossibleloglevels.performance:Oneofthepossibleloglevels.config:Oneofthepossibleloglevels.authorization:Oneofthepossibleloglevels.development:Oneofthepossibleloglevels.datafiles:Oneofthepossibleloglevels.views:Oneofthepossibleloglevels.ldap:Oneofthepossibleloglevels.replication:Oneofthepossibleloglevels.threads:Oneofthepossibleloglevels.audit-database:Oneofthepossibleloglevels.v8:Oneofthepossibleloglevels.

Monitoring

ssl:Oneofthepossibleloglevels.pregel:Oneofthepossibleloglevels.audit-collection:Oneofthepossibleloglevels.rocksdb:Oneofthepossibleloglevels.supervision:Oneofthepossibleloglevels.graphs:Oneofthepossibleloglevels.compactor:Oneofthepossibleloglevels.queries:Oneofthepossibleloglevels.heartbeat:Oneofthepossibleloglevels.requests:Oneofthepossibleloglevels.

ReturnCodes

200:isreturnediftherequestisvalid400:isreturnedwhentherequestbodycontainsinvalidJSON.405:isreturnedwhenaninvalidHTTPmethodisused.500:isreturnediftheservercannotgeneratetheresultduetoanout-of-memoryerror.

Reloadstheroutinginformation

Reloadtheroutingtable.

POST/_admin/routing/reload

Reloadstheroutinginformationfromthecollectionrouting.

ReturnCodes

200:Routinginformationwasreloadedsuccessfully.

Readthestatistics

returnthestatisticsinformation

GET/_admin/statistics

Returnsthestatisticsinformation.Thereturnedobjectcontainsthestatisticsfiguresgroupedtogetheraccordingtothedescriptionreturnedby_admin/statistics-description.Forinstance,toaccessafigureuserTimefromthegroupsystem,youfirstselectthesub-objectdescribingthegroupstoredinsystemandinthatsub-objectthevalueforuserTimeisstoredintheattributeofthesamename.

Incaseofadistribution,thereturnedobjectcontainsthetotalcountincountandthedistributionlistincounts.Thesum(ortotal)oftheindividualvaluesisreturnedinsum.

Example:

shell>curl--dump-http://localhost:8529/_admin/statistics

HTTP/1.1200OK

"time":1516907617.8872316,

"enabled":true,

"system":{

"minorPageFaults":76569,

"majorPageFaults":183,

"userTime":2.21,

"systemTime":0.49,

"numberOfThreads":48,

"residentSize":426942464,

"residentSizePercent":0.02556949617048751,

"virtualSize":3208433664

"client":{

Monitoring

"httpConnections":1,

"connectionTime":{

"sum":0,

"count":0,

"counts":[

"totalTime":{

"sum":12.890824556350708,

"count":4034,

"counts":[

"requestTime":{

"sum":0.030986785888671875,

"count":4034,

"counts":[

"queueTime":{

"sum":0.0002090930938720703,

"count":9,

"counts":[

"ioTime":{

"sum":12.859628677368164,

"count":4034,

"counts":[

"bytesSent":{

"sum":1794760,

"count":4034,

"counts":[

"bytesReceived":{

Monitoring

"sum":871054,

"count":4034,

"counts":[

"http":{

"requestsTotal":4034,

"requestsAsync":9,

"requestsGet":1019,

"requestsHead":0,

"requestsPost":2794,

"requestsPut":70,

"requestsPatch":3,

"requestsDelete":148,

"requestsOptions":0,

"requestsOther":0

"server":{

"uptime":19.03903317451477,

"physicalMemory":16697335808,

"v8Context":{

"available":4,

"busy":4,

"dirty":0,

"free":0,

"max":16

"threads":{

"running":8,

"working":4,

"blocked":0,

"queued":4

"error":false,

"code":200

ReturnCodes

200:Statisticswerereturnedsuccessfully.

Examples

shell>curl--dump-http://localhost:8529/_admin/statistics

HTTP/1.1200OK

showresponsebody

Statisticsdescription

fetchdescriptiveinfoofstatistics

GET/_admin/statistics-description

Returnsadescriptionofthestatisticsreturnedby/_admin/statistics.Thereturnedobjectscontainsanarrayofstatisticsgroupsintheattributegroupsandanarrayofstatisticsfiguresintheattributefigures.

Astatisticsgroupisdescribedby

Monitoring

group:Theidentifierofthegroup.name:Thenameofthegroup.description:Adescriptionofthegroup.

Astatisticsfigureisdescribedby

group:Theidentifierofthegrouptowhichthisfigurebelongs.identifier:Theidentifierofthefigure.Itisuniquewithinthegroup.name:Thenameofthefigure.description:Adescriptionofthefigure.type:Eithercurrent,accumulated,ordistribution.cuts:Thedistributionvector.units:Unitsinwhichthefigureismeasured.

Example:

shell>curl--dump-http://localhost:8529/_admin/statistics-description

HTTP/1.1200OK

"groups":[

"group":"system",

"name":"ProcessStatistics",

"description":"StatisticsabouttheArangoDBprocess"

"group":"client",

"name":"ClientConnectionStatistics",

"description":"Statisticsabouttheconnections."

"group":"http",

"name":"HTTPRequestStatistics",

"description":"StatisticsabouttheHTTPrequests."

"group":"server",

"name":"ServerStatistics",

"description":"StatisticsabouttheArangoDBserver"

"figures":[

"group":"system",

"identifier":"userTime",

"name":"UserTime",

"description":"Amountoftimethatthisprocesshasbeenscheduledinusermode,measuredinseconds.",

"type":"accumulated",

"units":"seconds"

"group":"system",

"identifier":"systemTime",

"name":"SystemTime",

"description":"Amountoftimethatthisprocesshasbeenscheduledinkernelmode,measuredinseconds.",

"units":"seconds"

"group":"system",

"identifier":"numberOfThreads",

"name":"NumberofThreads",

"description":"Numberofthreadsinthearangodprocess.",

"type":"current",

"units":"number"

Monitoring

"group":"system",

"identifier":"residentSize",

"name":"ResidentSetSize",

"description":"Thetotalsizeofthenumberofpagestheprocesshasinrealmemory.Thisisjustthepageswhichcount

towardtext,data,orstackspace.Thisdoesnotincludepageswhichhavenotbeendemand-loadedin,orwhichareswappedout.

Theresidentsetsizeisreportedinbytes.",

"type":"current",

"units":"bytes"

"group":"system",

"identifier":"residentSizePercent",

"name":"ResidentSetSize",

"description":"Thepercentageofphysicalmemoryusedbytheprocessasresidentsetsize.",

"type":"current",

"units":"percent"

"group":"system",

"identifier":"virtualSize",

"name":"VirtualMemorySize",

"description":"OnWindows,thisfigurecontainsthetotalamountofmemorythatthememorymanagerhascommittedforth

earangodprocess.Onothersystems,thisfigurecontainsThesizeofthevirtualmemorytheprocessisusing.",

"type":"current",

"units":"bytes"

"group":"system",

"identifier":"minorPageFaults",

"name":"MinorPageFaults",

"description":"Thenumberofminorfaultstheprocesshasmadewhichhavenotrequiredloadingamemorypagefromdisk.

ThisfigureisnotreportedonWindows.",

"units":"number"

"group":"system",

"identifier":"majorPageFaults",

"name":"MajorPageFaults",

"description":"OnWindows,thisfigurecontainsthetotalnumberofpagefaults.Onothersystem,thisfigurecontains

thenumberofmajorfaultstheprocesshasmadewhichhaverequiredloadingamemorypagefromdisk.",

"units":"number"

"group":"client",

"identifier":"httpConnections",

"name":"ClientConnections",

"description":"Thenumberofconnectionsthatarecurrentlyopen.",

"type":"current",

"units":"number"

"group":"client",

"identifier":"totalTime",

"name":"TotalTime",

"description":"Totaltimeneededtoanswerarequest.",

"type":"distribution",

"cuts":[

"units":"seconds"

"group":"client",

"identifier":"requestTime",

"name":"RequestTime",

"description":"Requesttimeneededtoanswerarequest.",

"cuts":[

Monitoring

"units":"seconds"

"group":"client",

"identifier":"queueTime",

"name":"QueueTime",

"description":"Queuetimeneededtoanswerarequest.",

"cuts":[

"units":"seconds"

"group":"client",

"identifier":"bytesSent",

"name":"BytesSent",

"description":"Bytessentsforarequest.",

"cuts":[

"units":"bytes"

"group":"client",

"identifier":"bytesReceived",

"name":"BytesReceived",

"description":"Bytesreceivedsforarequest.",

"cuts":[

"units":"bytes"

"group":"client",

"identifier":"connectionTime",

"name":"ConnectionTime",

"description":"Totalconnectiontimeofaclient.",

"cuts":[

"units":"seconds"

"group":"http",

"identifier":"requestsTotal",

"name":"Totalrequests",

"description":"TotalnumberofHTTPrequests.",

"units":"number"

Monitoring

"group":"http",

"identifier":"requestsAsync",

"name":"Asyncrequests",

"description":"NumberofasynchronouslyexecutedHTTPrequests.",

"units":"number"

"group":"http",

"identifier":"requestsGet",

"name":"HTTPGETrequests",

"description":"NumberofHTTPGETrequests.",

"units":"number"

"group":"http",

"identifier":"requestsHead",

"name":"HTTPHEADrequests",

"description":"NumberofHTTPHEADrequests.",

"units":"number"

"group":"http",

"identifier":"requestsPost",

"name":"HTTPPOSTrequests",

"description":"NumberofHTTPPOSTrequests.",

"units":"number"

"group":"http",

"identifier":"requestsPut",

"name":"HTTPPUTrequests",

"description":"NumberofHTTPPUTrequests.",

"units":"number"

"group":"http",

"identifier":"requestsPatch",

"name":"HTTPPATCHrequests",

"description":"NumberofHTTPPATCHrequests.",

"units":"number"

"group":"http",

"identifier":"requestsDelete",

"name":"HTTPDELETErequests",

"description":"NumberofHTTPDELETErequests.",

"units":"number"

"group":"http",

"identifier":"requestsOptions",

"name":"HTTPOPTIONSrequests",

"description":"NumberofHTTPOPTIONSrequests.",

"units":"number"

"group":"http",

"identifier":"requestsOther",

"name":"otherHTTPrequests",

"description":"NumberofotherHTTPrequests.",

"units":"number"

"group":"server",

"identifier":"uptime",

"name":"ServerUptime",

Monitoring

"description":"Numberofsecondselapsedsinceserverstart.",

"type":"current",

"units":"seconds"

"group":"server",

"identifier":"physicalMemory",

"name":"PhysicalMemory",

"description":"Physicalmemoryinbytes.",

"type":"current",

"units":"bytes"

"error":false,

"code":200

ReturnCodes

200:Descriptionwasreturnedsuccessfully.

Examples

shell>curl--dump-http://localhost:8529/_admin/statistics-description

HTTP/1.1200OK

showresponsebody

Returnroleofaserverinacluster

GettoknowwhetherthisserverisaCoordinatororDB-Server

GET/_admin/server/role

Returnstheroleofaserverinacluster.Theroleisreturnedintheroleattributeoftheresult.Possiblereturnvaluesforroleare:

SINGLE:theserverisastandaloneserverwithoutclusteringCOORDINATOR:theserverisacoordinatorinaclusterPRIMARY:theserverisaprimarydatabaseserverinaclusterSECONDARY:theserverisasecondarydatabaseserverinaclusterAGENT:theserverisanagencynodeinaclusterUNDEFINED:inacluster,UNDEFINEDisreturnediftheserverrolecannotbedetermined.

ReturnCodes

200:Isreturnedinallcases.

Returnidofaserverinacluster

Gettoknowtheinternalidoftheserver

GET/_admin/server/id

Returnstheidofaserverinacluster.Theidisemptyifitisworkinginsingleservermode.

ReturnCodes

QueriesstatisticsofDBserver

allowstoquerythestatisticsofaDBserverinthecluster

Monitoring

GET/_admin/clusterStatistics

QueryParameters

DBserver(required):

ReturnCodes

200:isreturnedwheneverythingwentwell.400:theparameterDBserverwasnotgivenorisnottheIDofaDBserver403:serverisnotacoordinator.

Monitoring

HTTPInterfaceforEndpointsTheAPI/_api/endpointisdeprecated.Forclustermodethereis/_api/cluster/endpointstofindallcurrentcoordinatorendpoints(seebelow).

TheArangoDBservercanlistenforincomingrequestsonmultipleendpoints.

TheendpointsarenormallyspecifiedeitherinArangoDB'sconfigurationfileoronthecommand-line,usingthe"--server.endpoint"option.ThedefaultendpointforArangoDBistcp://127.0.0.1:8529ortcp://localhost:8529.

Pleasenotethatallendpointmanagementoperationscanonlybeaccessedviathedefaultdatabase(_system)andnoneoftheotherdatabases.

AskingaboutEndpointsviaHTTP

Getinformationaboutallcoordinatorendpoints

ThisAPIcallreturnsinformationaboutallcoordinatorendpoints(clusteronly).

GET/_api/cluster/endpoints

Returnsanobjectwithanattributeendpoints,whichcontainsanarrayofobjects,whicheachhavetheattributeendpoint,whosevalueisastringwiththeendpointdescription.Thereisanentryforeachcoordinatorinthecluster.Thismethodonlyworksoncoordinatorsinclustermode.Incaseofanerrortheerrorattributeissettotrue.

ReturnCodes

200:isreturnedwheneverythingwentwell.403:serverisnotacoordinatorormethodwasnotGET.

Returnlistofallendpoints

ThisAPIcallreturnsthelistofallendpoints(singleserver).

GET/_api/endpoint

THISAPIISDEPRECATED

Returnsanarrayofallconfiguredendpointstheserverislisteningon.

TheresultisaJSONarrayofJSONobjects,eachwith`"entrypoint"'astheonlyattribute,andwiththevaluebeingastringdescribingtheendpoint.

Note:retrievingthearrayofallendpointsisallowedinthesystemdatabaseonly.Callingthisactioninanyotherdatabasewillmaketheserverreturnanerror.

Example:

shell>curl--dump-http://localhost:8529/_api/endpoint

HTTP/1.1200OK

"endpoint":"http://127.0.0.1:60154"

ReturnCodes

Endpoints

200:isreturnedwhenthearrayofendpointscanbedeterminedsuccessfully.400:isreturnediftheactionisnotcarriedoutinthesystemdatabase.405:TheserverwillrespondwithHTTP405ifanunsupportedHTTPmethodisused.

Examples

shell>curl--dump-http://localhost:8529/_api/endpoint

HTTP/1.1200OK

"endpoint":"http://127.0.0.1:60154"

Endpoints

FoxxHTTPAPITheseroutesallowmanipulatingtheFoxxservicesinstalledinadatabase.

FormoreinformationonFoxxanditsJavaScriptAPIsseetheFoxxchapterofthemaindocumentation.

FoxxServices

FoxxServiceManagementThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingFoxxservices.

Listinstalledservices

listinstalledservices

GET/_api/foxx

Fetchesalistofservicesinstalledinthecurrentdatabase.

Returnsalistofobjectswiththefollowingattributes:

mount:themountpathoftheservicedevelopment:trueiftheserviceisrunningindevelopmentmodelegacy:trueiftheserviceisrunningin2.8legacycompatibilitymodeprovides:theservicemanifest'sprovidesvalueoranemptyobject

Additionallytheobjectmaycontainthefollowingattributesiftheyhavebeensetonthemanifest:

name:astringidentifyingtheservicetypeversion:asemver-compatibleversionstring

ReturnCodes

200:Returnediftherequestwassuccessful.

Servicedescription

servicemetadata

GET/_api/foxx/service

Fetchesdetailedinformationfortheserviceatthegivenmountpath.

Returnsanobjectwiththefollowingattributes:

mount:themountpathoftheservicepath:thelocalfilesystempathoftheservicedevelopment:trueiftheserviceisrunningindevelopmentmodelegacy:trueiftheserviceisrunningin2.8legacycompatibilitymodemanifest:thenormalizedJSONmanifestoftheservice

Additionallytheobjectmaycontainthefollowingattributesiftheyhavebeensetonthemanifest:

name:astringidentifyingtheservicetypeversion:asemver-compatibleversionstring

QueryParameters

mount(required):Mountpathoftheinstalledservice.

ReturnCodes

200:Returnediftherequestwassuccessful.400:Returnedifthemountpathisunknown.

Installnewservice

installnewservice

POST/_api/foxx

Installsthegivennewserviceatthegivenmountpath.

Management

Therequestbodycanbeanyofthefollowingformats:

application/zip:arawzipbundlecontainingaserviceapplication/javascript:astandaloneJavaScriptfileapplication/json:aservicedefinitionasJSONmultipart/form-data:aservicedefinitionasamultipartform

Aservicedefinitionisanobjectorformwiththefollowingpropertiesorfields:

configuration:aJSONobjectdescribingconfigurationvaluesdependencies:aJSONobjectdescribingdependencysettingssource:afullyqualifiedURLoranabsolutepathontheserver'sfilesystem

Whenusingmultipartdata,thesourcefieldcanalsoalternativelybeafilefieldcontainingeitherazipbundleorastandaloneJavaScriptfile.

WhenusingastandaloneJavaScriptfilethegivenfilewillbeexecutedtodefineourservice'sHTTPendpoints.Itisthesamewhichwouldbedefinedinthefieldmainoftheservicemanifest.

IfsourceisaURL,theURLmustbereachablefromtheserver.Ifsourceisafilesystempath,thepathwillberesolvedontheserver.IneithercasethepathorURLisexpectedtoresolvetoazipbundle.

Notethatwhenusingfilesystempathsinaclusterwithmultiplecoordinatorsthefilesystempathmustresolvetoequivalentfilesoneverycoordinator.

QueryParameters

mount(required):Mountpaththeserviceshouldbeinstalledat.development(optional):Settotruetoenabledevelopmentmode.setup(optional):Settofalsetonotruntheservice'ssetupscript.legacy(optional):Settotruetoinstalltheservicein2.8legacycompatibilitymode.

ReturnCodes

Uninstallservice

uninstallservice

DELETE/_api/foxx/service

Removestheserviceatthegivenmountpathfromthedatabaseandfilesystem.

Returnsanemptyresponseonsuccess.

QueryParameters

mount(required):Mountpathoftheinstalledservice.teardown(optional):Settofalsetonotruntheservice'steardownscript.

ReturnCodes

Replaceservice

replaceaservice

PUT/_api/foxx/service

Removestheserviceatthegivenmountpathfromthedatabaseandfilesystem.Theninstallsthegivennewserviceatthesamemountpath.

Thisisaslightlysaferequivalenttoperforminganuninstalloftheoldservicefollowedbyinstallingthenewservice.Thenewservice'smainandscriptfiles(ifany)willbecheckedforbasicsyntaxerrorsbeforetheoldserviceisremoved.

Management

QueryParameters

mount(required):Mountpathoftheinstalledservice.teardown(optional):Settofalsetonotruntheoldservice'steardownscript.setup(optional):Settofalsetonotrunthenewservice'ssetupscript.legacy(optional):Settotruetoinstallthenewservicein2.8legacycompatibilitymode.

ReturnCodes

Upgradeservice

upgradeaservice

PATCH/_api/foxx/service

Installsthegivennewserviceontopoftheservicecurrentlyinstalledatthegivenmountpath.Thisisonlyrecommendedforswitchingbetweendifferentversionsofthesameservice.

Unlikereplacingaservice,upgradingaserviceretainstheoldservice'sconfigurationanddependencies(ifany)andshouldthereforeonlybeusedtomigrateanexistingservicetoanewerorequivalentservice.

Management

QueryParameters

mount(required):Mountpathoftheinstalledservice.teardown(optional):Settotruetoruntheoldservice'steardownscript.setup(optional):Settofalsetonotrunthenewservice'ssetupscript.legacy(optional):Settotruetoinstallthenewservicein2.8legacycompatibilitymode.

ReturnCodes

Management

FoxxServiceconfiguration/dependenciesThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingFoxxservicesconfigurationanddependencies.

Getconfigurationoptions

getconfigurationoptions

GET/_api/foxx/configuration

Fetchesthecurrentconfigurationfortheserviceatthegivenmountpath.

Returnsanobjectmappingtheconfigurationoptionnamestotheirdefinitionsincludingahuman-friendlytitleandthecurrentvalue(ifany).

QueryParameters

ReturnCodes

200:Returnediftherequestwassucessful.

Updateconfigurationoptions

updateconfigurationoptions

PATCH/_api/foxx/configuration

Replacesthegivenservice'sconfiguration.

Returnsanobjectmappingallconfigurationoptionnamestotheirnewvalues.

AJSONobjectmappingconfigurationoptionnamestotheirnewvalues.Anyomittedoptionswillbeignored.

QueryParameters

Replaceconfigurationoptions

replaceconfigurationoptions

PUT/_api/foxx/configuration

Replacesthegivenservice'sconfigurationcompletely.

Returnsanobjectmappingallconfigurationoptionnamestotheirnewvalues.

AJSONobjectmappingconfigurationoptionnamestotheirnewvalues.Anyomittedoptionswillberesettotheirdefaultvaluesormarkedasunconfigured.

QueryParameters

Getdependencyoptions

getdependencyoptions

GET/_api/foxx/dependencies

Fetchesthecurrentdependenciesforserviceatthegivenmountpath.

Configuration

Returnsanobjectmappingthedependencynamestotheirdefinitionsincludingahuman-friendlytitleandthecurrentmountpath(ifany).

QueryParameters

ReturnCodes

Updatedependenciesoptions

updatedependenciesoptions

PATCH/_api/foxx/dependencies

Replacesthegivenservice'sdependencies.

Returnsanobjectmappingalldependencynamestotheirnewmountpaths.

AJSONobjectmappingdependencynamestotheirnewmountpaths.Anyomitteddependencieswillbeignored.

QueryParameters

Replacedependenciesoptions

replacedependenciesoptions

PUT/_api/foxx/dependencies

Replacesthegivenservice'sdependenciescompletely.

Returnsanobjectmappingalldependencynamestotheirnewmountpaths.

AJSONobjectmappingdependencynamestotheirnewmountpaths.Anyomitteddependencieswillbedisabled.

QueryParameters

Configuration

FoxxServiceMiscellaneous

Listservicescripts

listservicescripts

GET/_api/foxx/scripts

Fetchesalistofthescriptsdefinedbytheservice.

Returnsanobjectmappingtherawscriptnamestohuman-friendlynames.

QueryParameters

ReturnCodes

Runservicescript

runservicescript

POST/_api/foxx/scripts/{name}

Runsthegivenscriptfortheserviceatthegivenmountpath.

Returnstheexportsofthescript,ifany.

RequestBody(optional)

AnarbitraryJSONvaluethatwillbeparsedandpassedtothescriptasitsfirstargument.

PathParameters

name(required):Nameofthescripttorun.

QueryParameters

ReturnCodes

Runservicetests

runservicetests

POST/_api/foxx/tests

Runsthetestsfortheserviceatthegivenmountpathandreturnstheresults.

Supportedtestreportersare:

default:asimplelistoftestcasessuite:anobjectoftestcasesnestedinsuitesstream:arawstreamoftestresultsxunit:anXUnit/JUnitcompatiblestructuretap:arawTAPcompatiblestream

TheAcceptrequestheadercanbeusedtofurthercontroltheresponseformat:

Whenusingthestreamreporterapplication/x-ldjsonwillresultintheresponsebodybeingformattedasanewline-delimitedJSONstream.

Whenusingthetapreportertext/plainortext/*willresultintheresponsebodybeingformattedasaplaintextTAPreport.

Miscellaneous

Whenusingthexunitreporterapplication/xmlortext/xmlwillresultintheresponsebodybeingformattedasXMLinsteadofJSONML.

Otherwisetheresponsebodywillbeformattedasnon-prettyprintedJSON.

QueryParameters

mount(required):Mountpathoftheinstalledservice.reporter(optional):Testreportertouse.idiomatic(optional):Usethematchingformatforthereporter,regardlessoftheAcceptheader.

ReturnCodes

Enabledevelopmentmode

enabledevelopmentmode

POST/_api/foxx/development

Putstheserviceintodevelopmentmode.

Whiletheserviceisrunningindevelopmentmodetheservicewillbereloadedfromthefilesystemanditssetupscript(ifany)willbere-executedeverytimetheservicehandlesarequest.

WhenrunningArangoDBinaclusterwithmultiplecoordinatorsnotethatchangestothefilesystemononecoordinatorwillnotbereflectedacrosstheothercoordinators.Thismeansyoushouldtreatyourcoordinatorsasinconsistentaslongasanyserviceisrunningindevelopmentmode.

QueryParameters

ReturnCodes

Disabledevelopmentmode

disabledevelopmentmode

DELETE/_api/foxx/development

Putstheserviceatthegivenmountpathintoproductionmode.

WhenrunningArangoDBinaclusterwithmultiplecoordinatorsthiswillreplacetheserviceonallothercoordinatorswiththeversiononthiscoordinator.

QueryParameters

ReturnCodes

ServiceREADME

serviceREADME

GET/_api/foxx/readme

Fetchestheservice'sREADMEorREADME.mdfile'scontentsifany.

QueryParameters

ReturnCodes

Miscellaneous

200:Returnediftherequestwassucessful.204:ReturnedifnoREADMEfilewasfound.

Swaggerdescription

swaggerdescription

GET/_api/foxx/swagger

FetchestheSwaggerAPIdescriptionfortheserviceatthegivenmountpath.

TheresponsebodywillbeanOpenAPI2.0compatibleJSONdescriptionoftheserviceAPI.

QueryParameters

ReturnCodes

Downloadservicebundle

downloadservicebundle

POST/_api/foxx/download

Downloadsazipbundleoftheservicedirectory.

Whendevelopmentmodeisenabled,thisalwayscreatesanewbundle.

OtherwisethebundlewillrepresenttheversionofaservicethatisinstalledonthatArangoDBinstance.

QueryParameters

ReturnCodes

200:Returnediftherequestwassucessful.400:Returnedifthemountpathisunknown.

Commitlocalservicestate

commitlocalservicestate

POST/_api/foxx/commit

Commitsthelocalservicestateofthecoordinatortothedatabase.

Thiscanbeusedtoresolveserviceconflictsbetweencoordinatorsthatcannotbefixedautomaticallyduetomissingdata.

QueryParameters

replace(optional):Overwriteexistingservicefilesindatabaseeveniftheyalreadyexist.204:Returnediftherequestwassucessful.

Miscellaneous

HTTPInterfaceforUserManagementThisisanintroductiontoArangoDB'sHTTPinterfaceformanagingusers.

Theinterfaceprovidesasimplemeanstoadd,update,andremoveusers.Allusersmanagedthroughthisinterfacewillbestoredinthesystemcollection_users.Youshouldnevermanipulatethe_userscollectiondirectly.

ThisspecializedinterfaceintentionallydoesnotprovideallfunctionalitythatisavailableintheregulardocumentRESTAPI.

PleasenotethatuseroperationsarenotincludedinArangoDB'sreplication.

CreateUser

Createanewuser.

POST/_api/user

passwd:Theuserpasswordasastring.Ifnopasswordisspecified,theemptystringwillbeused.IfyoupassthespecialvalueARANGODB_DEFAULT_ROOT_PASSWORD,thenthepasswordwillbesetthevaluestoredintheenvironmentvariableARANGODB_DEFAULT_ROOT_PASSWORD.ThiscanbeusedtopassaninstancevariableintoArangoDB.Forexample,theinstanceidentifierfromAmazon.active:Anoptionalflagthatspecifieswhethertheuserisactive.Ifnotspecified,thiswilldefaulttotrueuser:Thenameoftheuserasastring.Thisismandatory.extra:AnoptionalJSONobjectwitharbitraryextradataabouttheuser.

Createanewuser.YouneedserveraccesslevelAdministrateinordertoexecutethisRESTcall.

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/user<<EOF

"user":"admin@example",

"passwd":"secure"

HTTP/1.1201Created

"active":true,

"extra":{

"error":false,

"code":201

ReturnCodes

201:Returnediftheusercanbeaddedbytheserver400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.409:Returnedifauserwiththesamenamealreadyexists.

Examples

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/user<<EOF

UserManagement

"passwd":"secure"

HTTP/1.1201Created

showresponsebody

Setthedatabaseaccesslevel

Setthedatabaseaccesslevel.

PUT/_api/user/{user}/database/{dbname}

grant:Use"rw"tosetthedatabaseaccessleveltoAdministrate.Use"ro"tosetthedatabaseaccessleveltoAccess.Use"none"tosetthedatabaseaccessleveltoNoaccess.

Setsthedatabaseaccesslevelsforthedatabasedbnameofuseruser.YouneedtheAdministrateserveraccesslevelinordertoexecutethisRESTcall.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp/database/_system<<EOF

"grant":"rw"

HTTP/1.1200OK

"_system":"rw",

"error":false,

"code":200

PathParameters

user(required):Thenameoftheuser.dbname(required):Thenameofthedatabase.

ReturnCodes

200:Returnediftheaccesslevelwaschangedsuccessfully.400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.

Examples

http://localhost:8529/_api/user/admin@myapp/database/_system<<EOF

UserManagement

"grant":"rw"

HTTP/1.1200OK

showresponsebody

Setthecollectionaccesslevel

Setthecollectionaccesslevel.

PUT/_api/user/{user}/database/{dbname}/{collection}

grant:Use"rw"tosetthecollectionlevelaccesstoRead/Write.Use"ro"tosetthecollectionlevelaccesstoReadOnly.Use"none"tosetthecollectionlevelaccesstoNoaccess.

Setsthecollectionaccesslevelforthecollectioninthedatabasedbnameforuseruser.YouneedtheAdministrateserveraccesslevelinordertoexecutethisRESTcall.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp/database/_system/reports<<EOF

"grant":"rw"

HTTP/1.1200OK

"_system/reports":"rw",

"error":false,

"code":200

PathParameters

user(required):Thenameoftheuser.dbname(required):Thenameofthedatabase.collection(required):Thenameofthecollection.

ReturnCodes

200:Returnediftheaccesspermissionswerechangedsuccessfully.400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.

Examples

http://localhost:8529/_api/user/admin@myapp/database/_system/reports<<EOF

"grant":"rw"

UserManagement

HTTP/1.1200OK

showresponsebody

Clearthedatabaseaccesslevel

Clearthedatabaseaccesslevel,revertbacktothedefaultaccesslevel

DELETE/_api/user/{user}/database/{dbname}

PathParameters

user(required):Thenameoftheuser.dbname(required):Thenameofthedatabase.

Clearsthedatabaseaccesslevelforthedatabasedbnameofuseruser.Asconsequencethedefaultdatabaseaccesslevelisused.Ifthereisnodefineddefaultdatabaseaccesslevel,itdefaultstoNoaccess.Youneedpermissiontothe_systemdatabaseinordertoexecutethisRESTcall.

Notethatfortechnicalreasonsthiscurrentlyonlyworksinsingleservermode.Forclusters,usethePUTverbandanexplicitsettingfornow.

Example:

shell>curl-XDELETE--dump-http://localhost:8529/_api/user/admin@myapp/database/_system

HTTP/1.1202Accepted

"{\"error\":false,\"code\":202}"

ReturnCodes

202:Returnediftheaccesspermissionswerechangedsuccessfully.400:IftheJSONrepresentationismalformedormandatorydataismissingfromtherequest.

Examples

http://localhost:8529/_api/user/admin@myapp/database/_system

HTTP/1.1202Accepted

Clearthecollectionaccesslevel

Clearthecollectionaccesslevel,revertbacktothedefaultaccesslevel

DELETE/_api/user/{user}/database/{dbname}/{collection}

UserManagement

PathParameters

user(required):Thenameoftheuser.dbname(required):Thenameofthedatabase.collection(required):Thenameofthecollection.

Clearsthecollectionaccesslevelforthecollectioncollectioninthedatabasedbnameofuseruser.Asconsequencethedefaultcollectionaccesslevelisused.Ifthereisnodefineddefaultcollectionaccesslevel,itdefaultstoNoaccess.Youneedpermissionstothe_systemdatabaseinordertoexecutethisRESTcall.

Notethatfortechnicalreasonsthiscurrentlyonlyworksinsingleservermode.Forclusters,usethePUTverbandanexplicitsettingfornow.

Example:

shell>curl-XDELETE--dump-http://localhost:8529/_api/user/admin@myapp/database/_system/reports

HTTP/1.1202Accepted

ReturnCodes

202:Returnediftheaccesspermissionswerechangedsuccessfully.400:Iftherewasanerror

Examples

http://localhost:8529/_api/user/admin@myapp/database/_system/reports

HTTP/1.1202Accepted

Listtheaccessibledatabasesforauser

GET/_api/user/{user}/database/

PathParameters

user(required):Thenameoftheuserforwhichyouwanttoquerythedatabases.

QueryParameters

full(optional):Returnthefullsetofaccesslevelsforalldatabasesandallcollections.

Fetchthelistofdatabasesavailabletothespecifieduser.YouneedAdministratefortheserveraccesslevelinordertoexecutethisRESTcall.

ThecallwillreturnaJSONobjectwiththeper-databaseaccessprivilegesforthespecifieduser.Theresultobjectwillcontainthedatabasesnamesasobjectkeys,andtheassociatedprivilegesforthedatabaseasvalues.

Incaseyouspecifiedfull,theresultwillcontainthepermissionsforthedatabasesaswellasthepermissionsforthecollections.

UserManagement

Example:

shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/

HTTP/1.1200OK

"error":false,

"code":200,

"result":{

"_system":"rw"

Example:Withthefullresponseformat:

shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database?full=true

HTTP/1.1200OK

"error":false,

"code":200,

"result":{

"_system":{

"permission":"rw",

"collections":{

"_statisticsRaw":"undefined",

"_modules":"undefined",

"_queues":"undefined",

"_aqlfunctions":"undefined",

"_appbundles":"undefined",

"_graphs":"undefined",

"_routing":"undefined",

"_jobs":"undefined",

"animals":"undefined",

"_frontend":"undefined",

"_users":"undefined",

"_statistics":"undefined",

"_statistics15":"undefined",

"_apps":"undefined",

"demo":"undefined",

"*":"none"

"permission":"none"

ReturnCodes

200:Returnedifthelistofavailabledatabasescanbereturned.400:Iftheaccessprivilegesarenotrightetc.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.

Examples

shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/

UserManagement

HTTP/1.1200OK

showresponsebodyWiththefullresponseformat:

shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database?

full=true

HTTP/1.1200OK

showresponsebody

Getthedatabaseaccesslevel

Getspecificdatabaseaccesslevel

GET/_api/user/{user}/database/{database}

PathParameters

user(required):Thenameoftheuserforwhichyouwanttoquerythedatabases.database(required):Thenameofthedatabasetoquery

Fetchthedatabaseaccesslevelforaspecificdatabase

Example:

shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system

HTTP/1.1200OK

"error":false,

"code":200,

"result":"rw"

ReturnCodes

200:Returnediftheacccesslevelcanbereturned400:Iftheaccessprivilegesarenotrightetc.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.

Examples

shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system

HTTP/1.1200OK

UserManagement

showresponsebody

Getthespecificcollectionaccesslevel

Getthecollectionaccesslevel

GET/_api/user/{user}/database/{database}/{collection}

PathParameters

user(required):Thenameoftheuserforwhichyouwanttoquerythedatabases.database(required):Thenameofthedatabasetoquerycollection(required):Thenameofthecollection

Returnsthecollectionaccesslevelforaspecificcollection

Example:

shell>curl--dump-http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users

HTTP/1.1200OK

"error":false,

"code":200,

"result":"none"

ReturnCodes

200:Returnediftheacccesslevelcanbereturned400:Iftheaccessprivilegesarenotrightetc.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.

Examples

shell>curl--dump-

http://localhost:8529/_api/user/anotherAdmin@secapp/database/_system/_users

HTTP/1.1200OK

showresponsebody

ReplaceUser

Replaceanexistinguser.

PUT/_api/user/{user}

PathParameters

user(required):Thenameoftheuser

UserManagement

passwd:Theuserpasswordasastring.Specifyingapasswordismandatory,buttheemptystringisallowedforpasswordsactive:Anoptionalflagthatspecifieswhethertheuserisactive.Ifnotspecified,thiswilldefaulttotrueextra:AnoptionalJSONobjectwitharbitraryextradataabouttheuser.

Replacesthedataofanexistinguser.Thenameofanexistingusermustbespecifiedinuser.YouneedserveraccesslevelAdministrateinordertoexecutethisRESTcall.Additionally,ausercanchangehis/herowndata.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp<<EOF

"passwd":"secure"

HTTP/1.1200OK

"user":"admin@myapp",

"active":true,

"extra":{

"error":false,

"code":200

ReturnCodes

200:Isreturnediftheuserdatacanbereplacedbytheserver.400:TheJSONrepresentationismalformedormandatorydataismissingfromtherequest401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.404:Thespecifieduserdoesnotexist

Examples

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp

"passwd":"secure"

HTTP/1.1200OK

showresponsebody

ModifyUser

Modifyattributesofanexistinguser

PATCH/_api/user/{user}

PathParameters

UserManagement

passwd:Theuserpasswordasastring.Specifyingapasswordismandatory,buttheemptystringisallowedforpasswordsactive:Anoptionalflagthatspecifieswhethertheuserisactive.Ifnotspecified,thiswilldefaulttotrueextra:AnoptionalJSONobjectwitharbitraryextradataabouttheuser.

Partiallyupdatesthedataofanexistinguser.Thenameofanexistingusermustbespecifiedinuser.YouneedserveraccesslevelAdministrateinordertoexecutethisRESTcall.Additionally,ausercanchangehis/herowndata.

Example:

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp<<EOF

"passwd":"secure"

HTTP/1.1200OK

"active":true,

"extra":{

"error":false,

"code":200

ReturnCodes

200:Isreturnediftheuserdatacanbereplacedbytheserver.400:TheJSONrepresentationismalformedormandatorydataismissingfromtherequest.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.404:Thespecifieduserdoesnotexist

Examples

shell>curl-XPATCH--data-binary@---dump-http://localhost:8529/_api/user/admin@myapp

"passwd":"secure"

HTTP/1.1200OK

showresponsebody

RemoveUser

deleteauserpermanently.

DELETE/_api/user/{user}

PathParameters

UserManagement

Removesanexistinguser,identifiedbyuser.YouneedAdministratefortheserveraccesslevelinordertoexecutethisRESTcall.

Example:

shell>curl-XDELETE--data-binary@---dump-http://localhost:8529/_api/user/userToDelete@myapp<<EOF

HTTP/1.1202Accepted

"error":false,

"code":202

ReturnCodes

202:Isreturnediftheuserwasremovedbytheserver401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.404:Thespecifieduserdoesnotexist

Examples

shell>curl-XDELETE--data-binary@---dump-

http://localhost:8529/_api/user/userToDelete@myapp<<EOF

HTTP/1.1202Accepted

"error":false,

"code":202

FetchUser

fetchthepropertiesofauser.

GET/_api/user/{user}

PathParameters

Fetchesdataaboutthespecifieduser.YoucanfetchinformationaboutyourselforyouneedtheAdministrateserveraccesslevelinordertoexecutethisRESTcall.

Example:

shell>curl--dump-http://localhost:8529/_api/user/admin@myapp

UserManagement

HTTP/1.1200OK

"active":true,

"extra":{

"error":false,

"code":200

ReturnCodes

200:Theuserwasfound.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.404:Theuserwiththespecifiednamedoesnotexist.

Examples

shell>curl--dump-http://localhost:8529/_api/user/admin@myapp

HTTP/1.1200OK

showresponsebody

ListavailableUsers

fetchthepropertiesofauser.

GET/_api/user/

Fetchesdataaboutallusers.YouneedtheAdministrateserveraccesslevelinordertoexecutethisRESTcall.Otherwise,youwillonlygetinformationaboutyourself.

ThecallwillreturnaJSONobjectwithatleastthefollowingattributesonsuccess:

user:Thenameoftheuserasastring.active:Anoptionalflagthatspecifieswhethertheuserisactive.extra:AnoptionalJSONobjectwitharbitraryextradataabouttheuser.

Example:

shell>curl--dump-http://localhost:8529/_api/user

HTTP/1.1200OK

"error":false,

"code":200,

"result":[

"user":"admin",

"active":true,

"extra":{

UserManagement

"user":"root",

"active":true,

"extra":{

"user":"tester",

"active":false,

"extra":{

ReturnCodes

200:Theusersthatwerefound.401:ReturnedifyouhaveNoaccessdatabaseaccessleveltothe_systemdatabase.403:ReturnedifyouhaveNoaccessserveraccesslevel.

Examples

shell>curl--dump-http://localhost:8529/_api/user

HTTP/1.1200OK

showresponsebody

UserManagement

HTTPtasksInterfaceFollowingyouhaveArangoDB'sHTTPInterfaceforTasks.

TherearealsosomeexamplesprovidedforeveryAPIaction.

Fetchalltasksoronetask

Retrievesallcurrentlyactiveservertasks

GET/_api/tasks/

fetchesallexistingtasksontheserver

Example:Fetchingalltasks

shell>curl--dump-http://localhost:8529/_api/tasks

HTTP/1.1200OK

"id":"statistics-gc",

"name":"statistics-gc",

"created":1516907609.406109,

"type":"periodic",

"period":450,

"offset":406.020662,

"command":"(function(params){require('@arangodb/statistics').garbageCollector();})(params);",

"id":"statistics-average-collector",

"name":"statistics-average-collector",

"created":1516907609.4059584,

"type":"periodic",

"period":900,

"offset":20,

"command":"(function(params){require('@arangodb/statistics').historianAverage();})(params);",

"id":"statistics-collector",

"name":"statistics-collector",

"created":1516907609.4056144,

"type":"periodic",

"period":10,

"offset":1,

"command":"(function(params){require('@arangodb/statistics').historian();})(params);",

"id":"84",

"name":"user-definedtask",

"created":1516907599.4534233,

"type":"periodic",

"period":1,

"offset":0.000001,

"command":"(function(params){(function(){

require('@arangodb/foxx/queues/manager').manage();

})(params)})(params);",

200:Thelistoftasks

Examples

Fetchingalltasks

shell>curl--dump-http://localhost:8529/_api/tasks

HTTP/1.1200OK

"id":"statistics-gc",

"name":"statistics-gc",

"created":1516907609.406109,

"type":"periodic",

"period":450,

"offset":406.020662,

"command":"(function(params){require('@arangodb/statistics').garbageCollector();

})(params);",

"created":1516907609.4059584,

"type":"periodic",

"period":900,

"offset":20,

"command":"(function(params){require('@arangodb/statistics').historianAverage();

})(params);",

"id":"statistics-collector",

"name":"statistics-collector",

"created":1516907609.4056144,

"type":"periodic",

"period":10,

"offset":1,

"command":"(function(params){require('@arangodb/statistics').historian();})

(params);",

"id":"84",

"name":"user-definedtask",

"created":1516907599.4534233,

"type":"periodic",

"period":1,

"offset":0.000001,

"command":"(function(params){(function(){\n

require('@arangodb/foxx/queues/manager').manage();\n})(params)})(params);",

Fetchonetaskwithid

Retrievesonecurrentlyactiveservertask

GET/_api/tasks/{id}

id(required):Theidofthetasktofetch.

fetchesoneexistingtasksontheserverspecifiedbyid

Example:Fetchingasingletaskbyitsid

shell>curl--dump-http://localhost:8529/_api/tasks/statistics-average-collector

HTTP/1.1200OK

"created":1516907609.4059584,

"type":"periodic",

"period":900,

"offset":20,

"command":"(function(params){require('@arangodb/statistics').historianAverage();})(params);",

"error":false,

"code":200

Example:tryingtofetchanon-existingtask

shell>curl--dump-http://localhost:8529/_api/tasks/non-existing-task

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":1852,

"errorMessage":"tasknotfound"

200:Therequestedtask

Examples

Fetchingasingletaskbyitsid

shell>curl--dump-http://localhost:8529/_api/tasks/statistics-average-collector

HTTP/1.1200OK

showresponsebodytryingtofetchanon-existingtask

shell>curl--dump-http://localhost:8529/_api/tasks/non-existing-task

HTTP/1.1404NotFound

showresponsebody

createsatask

createsanewtask

POST/_api/tasks

params:Theparameterstobepassedintocommandoffset:Numberofsecondsinitialdelaycommand:TheJavaScriptcodetobeexecutedname:Thenameofthetaskperiod:numberofsecondsbetweentheexecutions

createsanewtaskwithageneratedid

Example:

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/tasks/<<EOF

"name":"SampleTask",

"command":"(function(params){require('@arangodb').print(params);})(params)",

"params":{

"foo":"bar",

"bar":"foo"

"period":2

HTTP/1.1200OK

"id":"12983",

"created":1516907628.2369483,

"type":"periodic",

"period":2,

"offset":0,

"command":"(function(params){(function(params){require('@arangodb').print(params);})(params)})(params);",

"error":false,

"code":200

shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/12983

ReturnCodes

400:Ifthepostbodyisnotaccurate,aHTTP400isreturned.

Examples

shell>curl-XPOST--data-binary@---dump-http://localhost:8529/_api/tasks/<<EOF

"params":{

"foo":"bar",

"bar":"foo"

"period":2

HTTP/1.1200OK

showresponsebody

createsataskwithid

registersanewtaskwithapre-definedid

PUT/_api/tasks/{id}

id(required):Theidofthetasktocreate

params:Theparameterstobepassedintocommandoffset:Numberofsecondsinitialdelaycommand:TheJavaScriptcodetobeexecutedname:Thenameofthetaskperiod:numberofsecondsbetweentheexecutions

registersanewtaskwiththespecifiedid

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/tasks/sampleTask<<EOF

"id":"SampleTask",

"params":{

"foo":"bar",

"bar":"foo"

"period":2

HTTP/1.1200OK

"id":"sampleTask",

"created":1516907628.2489061,

"type":"periodic",

"period":2,

"offset":0,

"command":"(function(params){(function(params){require('@arangodb').print(params);})(params)})(params);",

"error":false,

"code":200

ReturnCodes

400:Ifthetaskidalreadyexistsortherestbodyisnotaccurate,HTTP400isreturned.

Examples

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_api/tasks/sampleTask

"id":"SampleTask",

"params":{

"foo":"bar",

"bar":"foo"

"period":2

HTTP/1.1200OK

showresponsebody

deletesthetaskwithid

deletesonecurrentlyactiveservertask

DELETE/_api/tasks/{id}

id(required):Theidofthetasktodelete.

Deletesthetaskidentifiedbyidontheserver.

Example:tryingtodeletenonexistingtask

shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/NoTaskWithThatName

HTTP/1.1404NotFound

"error":true,

"code":404,

"errorNum":1852,

"errorMessage":"tasknotfound"

Example:RemoveexistingTask

shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/SampleTask

HTTP/1.1200OK

"error":false,

"code":200

ReturnCodes

404:Ifthetaskidisunknown,thenanHTTP404isreturned.

Examples

tryingtodeletenonexistingtask

shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/NoTaskWithThatName

HTTP/1.1404NotFound

showresponsebodyRemoveexistingTask

shell>curl-XDELETE--dump-http://localhost:8529/_api/tasks/SampleTask

HTTP/1.1200OK

"error":false,

"code":200

HTTPInterfaceforAgencyfeature

Configuration

Atalltimes,i.e.regardlessofthestateoftheagentsandthecurrenthealthoftheRAFTconsensus,onecaninvoketheconfigurationAPI:

curlhttp://$SERVER:$PORT/_api/agency/config

Here,andinallsubsequentcalls,weassumethat$SERVERisreplacedbytheservernameand$PORTisreplacedbytheportnumber.Weusecurlthroughoutfortheexamples,butanyclientlibraryperformingHTTPrequestsshoulddo.Theoutputmightlooksomewhatlikethis

"term":1,

"leaderId":"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98",

"lastCommitted":1,

"lastAcked":{

"ac129027-b440-4c4f-84e9-75c042942171":0.21,

"c54dbb8a-723d-4c82-98de-8c841a14a112":0.21,

"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98":0

"configuration":{

"pool":{

"ac129027-b440-4c4f-84e9-75c042942171":"tcp://localhost:8531",

"c54dbb8a-723d-4c82-98de-8c841a14a112":"tcp://localhost:8530",

"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98":"tcp://localhost:8529"

"active":[

"ac129027-b440-4c4f-84e9-75c042942171",

"c54dbb8a-723d-4c82-98de-8c841a14a112",

"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98"

"id":"f5d11cde-8468-4fd2-8747-b4ef5c7dfa98",

"agencysize":3,

"poolsize":3,

"endpoint":"tcp://localhost:8529",

"minping":0.5,

"maxping":2.5,

"supervision":false,

"supervisionfrequency":5,

"compactionstepsize":1000,

"supervisiongraceperiod":120

Thisistheactualoutputofahealthyagency.Theconfigurationoftheagencyisfoundintheconfigurationsectionasyoumighthaveguessed.Itispopulatedbystaticinformationonthestartupparameterslikeagencysize,theoncegenerateduniqueidetc.ItholdsinformationontheinvariantsoftheRAFTalgorithmanddatacompaction.

TheremainingdatareflectthevariantentitiesinRAFT,astermandleaderId,alsosomedebuginformationonhowlongthelastleadershipvotewasreceivedfromanyparticularagencymember.Lowtermnumbersonahealthynetworkareanindicationofgoodoperationenvironemnt,whileoftenincreasingtermnumbersindicate,thatthenetworkenvironemntandstabilitysuggesttoraisetheRAFTparametersminpingand'maxping'accordingly.

Key-ValuestoreAPIs

Generally,alldocumentIOtoandfromthekey-valuestoreconsistsofJSONarrays.TheouterArrayisanenvelopeformultiplereadorwritetransactions.Theresultsarearraysareanenvelopearoundtheresultscorrespondingtotheorderoftheincomingtransactions.

Considerthefollowingwriteoperationintoaprestineagency:

curl-Lhttp://$SERVER:$PORT/_api/agency/write-d'[[{"a":{"op":"set","new":{"b":{"c":[1,2,3]},"e":12}},"d":{"op":"set","new":f

alse}}]]'

Agency

[{results:[1]}]

Andthesubsequentreadoperation

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/"]]'

"c":[1,2,3]

"e":12

"d":false

InthefirststepwecommitedasingletransactionthatcommitstheJSONdocumentinsidetheinnertransactionarraytotheagency.Theresultis[1],whichisthereplicatedlogindex.Repeatedinvocationwillyieldgrowinglognumbers2,3,4,etc.

Thereadaccessisacompleteaccesstothekey-valuestoreindicatedbyaccesstoit'srootelementandreturnstheresultasanarraycorrespondingtotheoutermostarrayinthereadtransaction.

Let'sdiginsomedeeper.

ReadAPI

Let'sstartwiththeaboveinitialisedkey-valuestoreinthefollowing.Letusvisitthefollowingreadoperations:

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b"]]'

"c":[1,2,3]

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/c"]]'

"c":[1,2,3]

Notethattheaboveresultsareidentical,meaningthatresultsobtainedfromtheagencyarealwaysreturnwithfullpath.

Thesecondouterarraybracketsinreadoperationscorrespondtotransactions,meaningthattheresultisguaranteedtohavebeenacquiredwithoutawritetransactioninbetween:

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/e"],["/d","/a/b"]]'

Agency

"e":12

"c":[1,2,3

"d":false

Whilethefirsttransactionconsistsofasinglereadaccesstothekey-value-storethusstrechtingthemeaningofthewordtransaction,thesecondbracketactuallyholdtwodisjunctreadaccesses,whichhavebeenjoinedwithinzero-time,i.e.withoutawriteaccessinbetween.Thatistosaythat"/d"cannothavechangedbefore"/a/b"hadbeenacquired.

Let'strytofetchavaluefromthekey-value-store,whichdoesnotexist:

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/d"]]'

"b":{}

Theresultreturnsthecrosssectionoftherequestedpathandthekey-value-storecontents."/a/b"exists,butthereisnokey"/a/b/d".Thusthefollowingtransactionwillyield:

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/d","/d"]]'

"b":{}

"d":false

Andthislastreadoperationshouldreturn:

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/c"],["/a/b/d"],["/a/x/y"],["/y"],["/a/b","/a/x"]]'

{"a":{"b":{"c":[1,2,3]}}},

{"a":{"b":{}}},

{"a":{}},

{"a":{"b":{"c":[1,2,3]}}}

WriteAPI

Agency

ThewriteAPImustobviouslybemoreversatileandneedsamoredetailedappreciation.Writeoperationsarearraysoftransactionswithpreconditions,i.e.[[U,P]],wherethesystemtriestoapplyallupdatesintheouterarrayinturn,rejectingthosewhosepreconditionisnotfulfilledbythecurrentstate.Itisguaranteedthatthetransactionsinthewriterequestaresequencedadjacenttoeachother(withnointerventionfromotherwriterequests).Onlytheoneswithfailedpreconditionsareleftout.

ForP,thevalueofakeyisanobjectwithattributes"old","oldNot","oldEmpty"or"isArray".With"old"onecanspecifyaJSONvaluethathastobepresentfortheconditiontobefulfilled.With"oldNot"onemaycheckforavaluetonotbeequaltothetest.Whilewith"oldEmpty",whichcantakeabooleanvalue,onecanspecifythatthekeyvalueneedstobenotsettrueorsettoanarbitraryvaluefalse.With"isArray"onecanspecifythatthevaluemustbeanarray.Asashortcut,"old"valuesofscalarorarraytypemaybestoreddirectlyintheattribute.Examples:

{"/a/b/c":{"old":[1,2,3]}}

isapreconditionspecifyingthatthepreviousvalueofthekey"/a/b/c"keymustbe[1,2,3].Ifandonlyifthevalueofthepreconditionisnotanobjectweprovideanotation,wherethekeyworkoldmaybeomitted.Thus,theabovecheckmaybeshortcutas

{"/a/b/c":[1,2,3]}

Considertheagencyininitialisedasabovelet'sreviewtheresponsesfromtheagencyasfollows:

curl-Lhttp://$SERVER:$PORT/_api/agency/write-d'[[{"/a/b/c":{"op":"set","new":[1,2,3,4]},"/a/b/pi":{"op":"set","new":"somet

ext"}},{"/a/b/c":{"old":[1,2,3]}}]]'

"results":[19]

Theconditionisfulfilledinthefirstrunandwouldbewronginasecondreturning

"results":[0]

0asaresultmeansthatthepreconditionfailedandno"real"lognumberwasreturned.

{"/a/e":{"oldEmpty":false}}

meansthatthevalueofthekey"a/e"mustbeset(tosomething,whichcanbenull!).Thecondition

{"/a/e":{"oldEmpty":true}}

meansthatthevalueofthekey"a/e"mustbeunset.Thecondition

{"/a/b/c":{"isArray":true}}

meansthatthevalueofthekey"a/b/c"mustbeanarray.

TheupdatevalueUisanobject,theattributenamesareagainkeystringsandthevaluesareobjectswithoptionalattributes"new","op"and"ttl".Theyhavethefollowingmeaning:

"op"determinestheoperation,possiblevaluesare"set"(thedefault,ifleftout),"delete","increment","decrement","push","pop","shift"or"prepend"

"new"isthenewvalue,canbeomittedforthe"delete"operationandfor"increment"and"decrement",where1isimplied

"ttl",ifpresent,thenewvaluethatisbeingsetgetsatimetoliveinseconds,givenbyanumericvalueinthisattribute.Itisonlyguaranteedthattheactualremovalofthevalueisdoneaccordingtothesystemclock,souptoclockskewbetweenservers.Theremovalisdonebyanadditionalwritetransactionthatisautomaticallygeneratedbetweentheregularwrites.

Agency

Additionalrule:Ifnoneof"new"and"op"issetorthevalueisnotevenanobject,thenthisistobeinterpretedasifitwere

{"op":"set","new":<VALUE>}

whichamountstosettingthevaluewithnoprecondition.

Examples:

{"/a":{"op":"set","new":12}}

setsthevalueofthekey"/a"to12.Thesamecouldhavebeenachievedby

{"/a":12}

{"/a":{"new":12}}

Theoperation

{"/a/b":{"new":{"c":[1,2,3,4]}}}

setsthekey"/a/b"to{"c":[1,2,3,4]}.Notethatintheaboveexamplethisisthesameassettingthevalueof"/a/b/c"to[1,2,3,4].Thedifferenceis,thatifa/bhadothersubattributes,thenthistransactionwoulddeletealltheseotherattributesandmake"/a/b"equalto{"c":[1,2,3,4]},whereassetting"/a/b/c"to[1,2,3,4]wouldretainallattributesotherthan"c"in"/a/b".

Herearesomemoreexamplesforfulltransactions(update/preconditionpairs).Thetransaction

[{"/a/b":{"new":{"c":[1,2,3,4]}}},

{"/a/b":{"old":{"c":[1,2,3]}}}]

setsthekey"/a/b"to{"c":[1,2,3,4]}ifandonlyifitwas{"c":[1,2,3]}before.Notethatthisfailsif"/a/b"hadotherattributesthan"c".Thetransaction

[{"/x":{"op":"delete"}},

{"/x":{"old":false}}]

clearsthevalueofthekey"/x"ifthisoldvaluewasfalse.

[{"/y":{"new":13},

{"/y":{"oldEmpty":true}}}

setsthevalueof"/y"to13,butonly,ifitwasunsetbefore.

[{"/z":{"op":"push","new":"Max"}}]

appendsthestring"Max"totheendoftheliststoredinthe"z"attribute,orcreatesanarray["Max"]in"z"ifitwasunsetornotanarray.

[{"/u":{"op":"pop"}}]

removesthelastentryofthearraystoredunder"u",ifthevalueof"u"isnotsetornotanarray.

HTTP-headersforwriteoperations

X-ArangoDB-Agency-Modewithpossiblevalues"waitForCommitted","waitForSequenced"and"noWait".

Agency

Inthefirstcasethewriteoperationonlyreturnswhenthecommittothereplicatedloghasactuallyhappened.Inthesecondcasethewriteoperationreturnswhenthewritetransactionsthatfulfilledtheirpreconditionshavebeensequencedandthusitisknown,whichofthewritetransactionsinthegivenarrayhadfulfilledpreconditions.InbothcasesthebodyisaJSONarraycontainingtheindexesofthetransactionsinthelistthathadfulfilledpreconditions.

Inthelastcase,"noWait",theoperationreturnsimmediately,anemptybodyisreturned.Togetanyinformationabouttheresultoftheoperationonehastospecifyatag(seebelow)andaskaboutthestatuslateron.

X-ArangoDB-Agency-TagwithanarbitraryUTF-8stringvalue.

Observers

Externalservicestotheagencymayannouncethemselvesorotherstobeobserversofarbitraryexistingorfuturekeysinthekey-value-store.Theagencymusttheninformtheobservingserviceofanychangestothesubtreebelowtheobservedkey.ThenotificationisdonebyvirtueofPOSTrequeststoarequiredvalidURL.

Inordertoobserveanyfuturemodificationbelowsay"/a/b/c",aobserverisannouncedthroughpostingthebelowdocumenttotheagency’swriteRESThandler:

[{"/a/b/c":

{"op":"observe",

"url":"http://<host>:<port>/<path>"

Theobserverisnotifiedofanychangestothattargetuntilsuchtimethatitremovesitselfasanobserverofthatkeythrough

[{"/a/b/c":

{"op":"unobserve",

"url":“http://<host>:<port>/<path>"}}]

Notethatthelastdocumentremovesallobservationsfromentitiesbelow"/a/b/c".Inparticular,issuing

[{"/":"unobserve","url":"http://<host>:<port>/<path>"}]

willresultintheremovalofallobservationsforURL"http://<host>:<port>/<path>".ThenotifyingPOSTrequestsaresubmittedimmediatelywithanycompletearrayofchangestothereaddboftheleaderofcreate,modifyanddeleteeventsaccordingly;Thebody

{"term":"5",

"index":167,

"/a/b/c":{"op":"modify","old":1,"new":2}},

"/constants/euler":{"op":"create","new":2.718281828459046},

"/constants/pi":{"op":"delete"}}}

Agency

HTTPInterfaceforMiscellaneousfunctionsThisisanoverviewofArangoDB'sHTTPinterfaceformiscellaneousfunctions.

Returnserverversion

returnstheserverversionnumber

GET/_api/version

QueryParameters

details(optional):Ifsettotrue,theresponsewillcontainadetailsattributewithadditionalinformationaboutincludedcomponentsandtheirversions.TheattributenamesandinternalsofthedetailsobjectmayvarydependingonplatformandArangoDBversion.

Returnstheservernameandversionnumber.TheresponseisaJSONobjectwiththefollowingattributes:

HTTP200

isreturnedinallcases.

version:theserverversionstring.Thestringhastheformat"major.minor.sub".majorandminorwillbenumeric,andsubmaycontainanumberoratextualversion.details:anoptionalJSONobjectwithadditionaldetails.Thisisreturnedonlyifthedetailsqueryparameterissettotrueintherequest.server:willalwayscontainarango

Example:Returntheversioninformation

shell>curl--dump-http://localhost:8529/_api/version

HTTP/1.1200OK

"server":"arango",

"version":"3.3.3",

Example:Returntheversioninformationwithdetails

shell>curl--dump-http://localhost:8529/_api/version?details=true

HTTP/1.1200OK

"server":"arango",

"version":"3.3.3",

"license":"community",

"details":{

"architecture":"64bit",

"arm":"false",

"asan":"false",

"asm-crc32":"true",

"assertions":"true",

"boost-version":"1.62.0",

"build-date":"2018-01-2519:30:05",

"build-repository":"heads/3.3.3-0-gd1ca58310e-dirty",

"compiler":"gcc[7.2.0]",

"cplusplus":"201103",

"debug":"false",

"endianness":"little",

"failure-tests":"false",

"fd-client-event-handler":"poll",

"fd-setsize":"1024",

"full-version-string":"ArangoDB3.3.3[linux]64bitmaintainermode,usingjemalloc,VPack0.1.30,RocksDB5.6.0,ICU58.

1,V85.7.492.77,OpenSSL1.0.2g1Mar2016",

"icu-version":"58.1",

"jemalloc":"true",

"maintainer-mode":"true",

"openssl-version":"OpenSSL1.0.2g1Mar2016",

"platform":"linux",

"reactor-type":"epoll",

"rocksdb-version":"5.6.0",

"server-version":"3.3.3",

"sizeofint":"4",

"sizeofvoid*":"8",

"sse42":"false",

"unaligned-access":"true",

"v8-version":"5.7.492.77",

"vpack-version":"0.1.30",

"zlib-version":"1.2.11",

"mode":"server",

"host":"c54ebb83e5eb4257b9e0f7201ba87ded"

ReturnCodes

200:isreturnedinallcases.

ResponseBody

version:theserverversionstring.Thestringhastheformat"major.minor.sub".majorandminorwillbenumeric,andsubmaycontainanumberoratextualversion.details:anoptionalJSONobjectwithadditionaldetails.Thisisreturnedonlyifthedetailsqueryparameterissettotrueintherequest.server:willalwayscontainarango

shell>curl--dump-http://localhost:8529/_api/version

HTTP/1.1200OK

showresponsebodyReturntheversioninformationwithdetails

shell>curl--dump-http://localhost:8529/_api/version?details=true

HTTP/1.1200OK

showresponsebody

Returnserverdatabaseenginetype

returnstheenginethetypetheserverisrunningwith

GET/_api/engine

Returnsthestorageenginetheserverisconfiguredtouse.TheresponseisaJSONobjectwiththefollowingattributes:

HTTP200

isreturnedinallcases.

name:willbemmfilesorrocksdb

Example:Returntheactivestorageengine

shell>curl--dump-http://localhost:8529/_api/engine

HTTP/1.1200OK

"name":"mmfiles",

"supports":{

"dfdb":true,

"indexes":[

"primary",

"edge",

"hash",

"skiplist",

"persistent",

"geo",

"fulltext"

ReturnCodes

ResponseBody

name:willbemmfilesorrocksdb

shell>curl--dump-http://localhost:8529/_api/engine

HTTP/1.1200OK

showresponsebody

Flushesthewrite-aheadlog

SynctheWALtodisk.

PUT/_admin/wal/flush

PathParameters

waitForSync(optional):Whetherornottheoperationshouldblockuntilthenot-yetsynchronizeddatainthewrite-aheadlogwassynchronizedtodisk.waitForCollector(optional):Whetherornottheoperationshouldblockuntilthedataintheflushedloghasbeencollectedbythewrite-aheadloggarbagecollector.Notethatsettingthisoptiontotruemightblockforalongtimeiftherearelong-runningtransactionsandthewrite-aheadloggarbagecollectorcannotfinishgarbagecollection.

Flushesthewrite-aheadlog.Byflushingthecurrentlyactivewrite-aheadlogfile,thedatainitcanbetransferredtocollectionjournalsanddatafiles.Thisisusefultoensurethatalldataforacollectionispresentinthecollectionjournalsanddatafiles,forexample,whendumpingthedataofacollection.

ReturnCodes

200:Isreturnediftheoperationsucceeds.405:isreturnedwhenaninvalidHTTPmethodisused.

Retrievestheconfigurationofthewrite-aheadlog

fetchthecurrentconfiguration.

GET/_admin/wal/properties

Retrievestheconfigurationofthewrite-aheadlog.TheresultisaJSONobjectwiththefollowingattributes:

allowOversizeEntries:whetherornotoperationsthatarebiggerthanasinglelogfilecanbeexecutedandstoredlogfileSize:thesizeofeachwrite-aheadlogfilehistoricLogfiles:themaximumnumberofhistoriclogfilestokeepreserveLogfiles:themaximumnumberofreservelogfilesthatArangoDBallocatesinthebackgroundsyncInterval:theintervalforautomaticsynchronizationofnot-yetsynchronizedwrite-aheadlogdata(inmilliseconds)throttleWait:themaximumwaittimethatoperationswillwaitbeforetheygetabortedifcaseofwrite-throttling(inmilliseconds)throttleWhenPending:thenumberofunprocessedgarbage-collectionoperationsthat,whenreached,willactivatewrite-throttling.Avalueof0meansthatwrite-throttlingwillnotbetriggered.

Example:

shell>curl--dump-http://localhost:8529/_admin/wal/properties

HTTP/1.1200OK

"allowOversizeEntries":true,

"logfileSize":33554432,

"historicLogfiles":10,

"reserveLogfiles":3,

"syncInterval":100,

"throttleWait":15000,

"throttleWhenPending":0

ReturnCodes

Configuresthewrite-aheadlog

configureparametersofthewal

PUT/_admin/wal/properties

Configuresthebehaviorofthewrite-aheadlog.ThebodyoftherequestmustbeaJSONobjectwiththefollowingattributes:

allowOversizeEntries:whetherornotoperationsthatarebiggerthanasinglelogfilecanbeexecutedandstoredlogfileSize:thesizeofeachwrite-aheadlogfilehistoricLogfiles:themaximumnumberofhistoriclogfilestokeepreserveLogfiles:themaximumnumberofreservelogfilesthatArangoDBallocatesinthebackgroundthrottleWait:themaximumwaittimethatoperationswillwaitbeforetheygetabortedifcaseofwrite-throttling(inmilliseconds)throttleWhenPending:thenumberofunprocessedgarbage-collectionoperationsthat,whenreached,willactivatewrite-throttling.Avalueof0meansthatwrite-throttlingwillnotbetriggered.

Specifyinganyoftheaboveattributesisoptional.Notspecifiedattributeswillbeignoredandtheconfigurationforthemwillnotbemodified.

Example:

shell>curl-XPUT--data-binary@---dump-http://localhost:8529/_admin/wal/properties<<EOF

"allowOversizeEntries":true

HTTP/1.1200OK

"allowOversizeEntries":true,

"historicLogfiles":10,

"reserveLogfiles":3,

"syncInterval":100,

"throttleWait":15000,

"throttleWhenPending":0

ReturnCodes

Returnsinformationaboutthecurrentlyrunningtransactions

returnsinformationaboutthecurrentlyrunningtransactions

GET/_admin/wal/transactions

Returnsinformationaboutthecurrentlyrunningtransactions.TheresultisaJSONobjectwiththefollowingattributes:

runningTransactions:numberofcurrentlyrunningtransactionsminLastCollected:minimumidofthelastcollectedlogfile(atthestartofeachrunningtransaction).Thisisnullifnotransactionisrunning.minLastSealed:minimumidofthelastsealedlogfile(atthestartofeachrunningtransaction).Thisisnullifnotransactionisrunning.

Example:

shell>curl--dump-http://localhost:8529/_admin/wal/transactions

HTTP/1.1200OK

"runningTransactions":5,

"minLastCollected":85,

"minLastSealed":null

ReturnCodes

Returnsystemtime

Getthecurrenttimeofthesystem

GET/_admin/time

Thecallreturnsanobjectwiththeattributetime.ThiscontainsthecurrentsystemtimeasaUnixtimestampwithmicrosecondprecision.

ReturnCodes

200:Timewasreturnedsuccessfully.

Returncurrentrequest

Sendbackwhatwassentin,headers,postbodyetc.

GET/_admin/echo

Thecallreturnsanobjectwiththefollowingattributes:

headers:objectwithHTTPheadersreceived

requestType:theHTTPrequestmethod(e.g.GET)

parameters:objectwithqueryparametersreceived

ReturnCodes

200:Echowasreturnedsuccessfully.

Returncurrentrequestandcontinues

Sendbackwhatwassentin,headers,postbodyetc.

GET/_admin/long_echo

Thecallreturnsanobjectwiththefollowingattributes:

headers:objectwithHTTPheadersreceived

requestType:theHTTPrequestmethod(e.g.GET)

parameters:objectwithqueryparametersreceived

ReturnCodes

200:Echowasreturnedsuccessfully.

Returntherequiredversionofthedatabase

returnstheversionofthedatabase.

GET/_admin/database/target-version

Returnsthedatabase-versionthatthisserverrequires.Theversionisreturnedintheversionattributeoftheresult.

ReturnCodes

Initiateshutdownsequence

initiatestheshutdownsequence

DELETE/_admin/shutdown

Thiscallinitiatesacleanshutdownsequence.Requiresadministriveprivileges

ReturnCodes

Runstestsonserver

showtheavailableunittestsontheserver.

POST/_admin/test

AJSONobjectcontaininganattributetestswhichliststhefilescontainingthetestsuites.

Executesthespecifiedtestsontheserverandreturnsanobjectwiththetestresults.Theobjecthasanattribute"error"whichstateswhetheranyerroroccurred.Theobjectalsohasanattribute"passed"whichindicateswhichtestspassedandwhichdidnot.

Executeprogram

Executeascriptontheserver.

POST/_admin/execute

Thebodytobeexecuted.

Executesthejavascriptcodeinthebodyontheserverasthebodyofafunctionwithnoarguments.Ifyouhaveareturnstatementthenthereturnvalueyouproducewillbereturnedascontenttypeapplication/json.IftheparameterreturnAsJSONissettotrue,theresultwillbeaJSONobjectdescribingthereturnvaluedirectly,otherwiseastringproducedbyJSON.stringifywillbereturned.

NotethatthisAPIendpointwillonlybepresentiftheserverwasstartedwiththeoption--javascript.allow-admin-executetrue.

Thedefaultvalueofthisoptionisfalse,whichdisablestheexecutionofuser-definedcodeanddisablesthisAPIendpointentirely.Thisisalsotherecommendedsettingforproduction.

Table of Contents - ArangoDB · 2018. 1. 26. · ArangoDB v3.3.3 HTTP API Documentation Welcome to...

Documents

Transcript of Table of Contents - ArangoDB · 2018. 1. 26. · ArangoDB v3.3.3 HTTP API Documentation Welcome to...

MediaMatrix API Documentation

Rupy2012 ArangoDB Workshop Part1

FAXAGE Web API Documentation

Govee API Documentation

SMPP API Supplementary Documentation...SMPP API Supplementary Documentation MessageMedia - SMPP API Supplementary Documentation 4 1.6 Throughput Throughput per bind is dependent on

DPD API Reference Documentation

ETradeFinancial-API Technical Documentation

Rapid API Development ArangoDB Foxx

ActiveX API Documentation

Web Faction API Documentation

Grou.ps API Documentation 2015

TeamViewer API Documentation

Bitbucket-API Documentation

Making API documentation work

LSMaker API documentation v0.0

Live API Documentation

Graphite-API Documentation

nextcloud-API Documentation

csgo Documentation - Read the Docs · API Documentation 2.1csgo API ... EMsgGCToGCBroadcastConsoleCommand = 2521 EMsgGCToGCDirtyMultipleSDOCache = 2517 ... csgo Documentation, Release

KissCartoon API Documentation - media.readthedocs.org · KissCartoon API Documentation, Release 0.1 KissCartoon is an unofﬁcial API forkisscartoon.iowebsite. It’s written for