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

1.1

1.2

1.3

1.4

1.4.1

1.4.2

1.4.3

1.5

1.5.1

1.5.2

1.5.3

1.6

1.6.1

1.6.2

1.7

1.7.1

1.7.2

1.8

1.8.1

1.8.2

1.8.3

1.9

1.10

1.10.1

1.10.2

1.11

1.12

1.13

1.14

1.15

1.16

1.16.1

1.16.2

1.16.3

1.16.4

1.17

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

Edges

AddressandEtag

WorkingwithEdges

GeneralGraph

Management

Vertices

Edges

Traversals

AQLQueryCursors

QueryResults

AccessingCursors

AQLQueries

AQLQueryCache

AQLUserFunctionsManagement

SimpleQueries

AsyncResultHandling

BulkImport/Export

JSONDocuments

Headers&Values

BatchRequests

Exportingdata

Indexes

WorkingwithIndexes

Hash

Skiplist

Persistent

Geo

1

1.17.6

1.18

1.19

1.19.1

1.19.2

1.19.3

1.19.4

1.20

1.21

1.22

1.23

1.23.1

1.23.2

1.23.3

1.24

1.25

1.26

1.27

Fulltext

Transactions

Replication

ReplicationDump

ReplicationLogger

ReplicationApplier

OtherReplicationCommands

Sharding

Monitoring

Endpoints

FoxxServices

Management

Configuration

Miscellaneous

UserManagement

Tasks

Agency

Miscellaneousfunctions

2

ArangoDBv3.3.3HTTPAPIDocumentationWelcometotheArangoDBHTTPAPIdocumentation!ThisdocumentationisforAPIdevelopers.AsauseroradministratorofArangoDByoushouldnotneedtheinformationprovidedherein.

Ingeneral,asauserofArangoDByouwilluseoneofthelanguagedrivers.

Introduction

3

https://www.arangodb.com/drivers/

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

4

http://tools.ietf.org/html/rfc5789

http://www.json.org

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

5

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

6

https://jwt.io

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

7

https://fetch.spec.whatwg.org/#cors-protocol-and-credentials

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

8

https://developer.mozilla.org/en-US/docs/Web/API/XMLHttpRequest/withCredentials

HTTPInterfaceFollowingyouhaveArangoDB'sHTTPInterfaceforDocuments,Databases,Edgesandmore.

TherearealsosomeexamplesprovidedforeveryAPIaction.

YoumayalsousetheinteractiveSwaggerdocumentationintheArangoDBwebinterfacetoexploretheAPIcallsbelow.

HTTPInterface

9

http://swagger.io

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

10

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?

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

[]yes

["_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

11

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

12


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

13

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

14

EOF

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

}

]

}

EOF

HTTP/1.1201Created



{

"error":false,

"code":201,

"result":true

}


{

"name":"example"

}

EOF

HTTP/1.1201Created



showresponsebodyCreatingadatabasenamedmydbwithtwousers.


{

"name":"mydb",

"users":[

{

Management

15

"username":"admin",

"passwd":"secret",

"active":true

},

{

"username":"tester",

"passwd":"test001",

"active":false

}

]

}

EOF

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

16


showresponsebody

Management

17

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



Foxxapplicationsarealsoorganizedindatabase-specificdirectoriesinsidetheapplicationpath.Thefilesystemlayoutcouldlooklikethis:

apps/#theinstance'sapplicationdirectory

system/#systemapplications(canbeignored)

databases/#sub-directorycontainingdatabase-specificapplications

<database-name>/#sub-directoryforasingledatabase

<app-name>#sub-directoryforasingleapplication

NotesonDatabases

18


<database-name>/#sub-directoryforanotherdatabase


`

NotesonDatabases

19

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

20

collectionnameshouldbeused,i.e.:

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

Forexample:Assumethatthecollectionidentifieris7254820andthecollectionnameisdemo,thentheURLofthatcollectionis:

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

Collections

21

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

22

collectionsalonewillgeneratewarnings,whichcanbeoverridden,aboutmissingshardingprototype.

Createsanewcollectionwithagivenname.Therequestmustcontainanobjectwiththefollowingattributes.

Example:

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

{

"name":"testCollectionBasics"

}

EOF

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

}

EOF

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

23

Example:


{

"name":"testCollectionUsers",

"keyOptions":{

"type":"autoincrement",

"increment":5,

"allowUserKeys":true

}

}

EOF

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"

}

EOF

HTTP/1.1200OK



showresponsebody


{


"keyOptions":{


"increment":5,

"allowUserKeys":true

}

}

EOF

Creating

24

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

25

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

26

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

27

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

28

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

29

"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

30

"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

31

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

32

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

33

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

34

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

35



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

36

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

37

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

38

"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

39

200:Thelistofcollections

Examples

Returninformationaboutallcollections:

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

HTTP/1.1200OK



showresponsebody

GettingInformation

40

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

41

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

42



location:/_api/collection/products/unload

showresponsebody

LoadIndexesintoMemory

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

43

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

}

EOF

HTTP/1.1200OK




{

"code":200,

"error":false,

Modifying

44

"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

}

EOF

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

45


Ifrenamingthecollectionsucceeds,thenthecollectionisalsorenamedinallgraphdefinitionsinsidethe_graphscollectioninthecurrentdatabase.

Note:thismethodisnotavailableinacluster.

Example:

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

{

"name":"newname"

}

EOF

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"

}

EOF

HTTP/1.1200OK



location:/_api/collection/products1/rename

showresponsebody

Rotatejournalofacollection

rotatesthejournalofacollection

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

PathParameters


Modifying

46

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

{

}

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

{

}

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

47

}

EOF

HTTP/1.1200OK



location:/_api/collection/products/rotate

showresponsebodyRotatingifnojournalexists:


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

{

}

EOF




showresponsebody

Modifying

48

HTTPInterfaceforDocumentsInthischapterwedescribetheRESTAPIofArangoDBfordocuments.

BasicapproachDetailedAPIdescription

Documents

49


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.


50

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.


51

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


52

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,


53

"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


54

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"


55

}

EOF

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"

}

EOF

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

}


56

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

<<EOF

{


}

EOF

HTTP/1.1201Created



showresponsebodyReturnalldocumentkeys

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

<<EOF

{


"type":"id"

}

EOF

HTTP/1.1201Created



showresponsebodyCollectiondoesnotexist

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


57

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


58

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"}

EOF

HTTP/1.1201Created



etag:"_WQ47YT6--_"

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

{


"_key":"10976",

"_rev":"_WQ47YT6--_"

}

Example:Createadocumentinacollectionnamedproductswithacollection-levelwaitForSyncvalueoffalse.


{"Hello":"World"}

EOF

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"}

EOF

HTTP/1.1201Created



etag:"_WQ47YW6--_"


{


"_key":"11027",

"_rev":"_WQ47YW6--_"


59

}

Example:Unknowncollectionname


{"Hello":"World"}

EOF

HTTP/1.1404NotFound



{

"error":true,


"code":404,

"errorNum":1203

}

Example:Illegaldocument


{1:"World"}

EOF




{

"error":true,

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

"code":400,

"errorNum":600

}

Example:Insertmultipledocuments:


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

EOF

HTTP/1.1202Accepted



[

{


"_key":"10991",

"_rev":"_WQ47YUa--_"

},

{


"_key":"10995",

"_rev":"_WQ47YUa--B"

},

{


60


"_key":"10997",

"_rev":"_WQ47YUa--D"

}

]

Example:UseofreturnNew:

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

{"Hello":"World"}

EOF

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

<<EOF

{"Hello":"World"}

EOF

HTTP/1.1201Created



etag:"_WQ47YT6--_"


showresponsebody


61

Createadocumentinacollectionnamedproductswithacollection-levelwaitForSyncvalueoffalse.


<<EOF

{"Hello":"World"}

EOF

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"}

EOF

HTTP/1.1201Created



etag:"_WQ47YW6--_"


showresponsebodyUnknowncollectionname


<<EOF

{"Hello":"World"}

EOF

HTTP/1.1404NotFound



showresponsebodyIllegaldocument


<<EOF

{1:"World"}

EOF





62

showresponsebodyInsertmultipledocuments:


<<EOF

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

EOF

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"}

EOF

HTTP/1.1202Accepted



etag:"_WQ47YU2--_"


showresponsebody


ThecollectionnameshouldnowbespecifiedintheURLpath.TheoldwaywiththeURLpath/_api/documentandtherequiredqueryparametercollectionstillworks.ThepossibilitytoinsertmultipledocumentswithoneoperationisnewandthequeryparameterreturnNewhasbeenadded.

Replacedocument

replacesadocument


63

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"}

EOF


64

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

{}

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"}

EOF

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.


65

Examples

Usingadocumenthandle


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

{"Hello":"you"}

EOF

HTTP/1.1202Accepted



etag:"_WQ47Yd6--A"


showresponsebodyUnknowndocumenthandle



{}

EOF

HTTP/1.1404NotFound



showresponsebodyProducearevisionconflict

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


{"other":"content"}

EOF




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.


66


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.


67


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.


68

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"

}

EOF

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

}

}

EOF

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,


69

"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

}

}

EOF

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,


70

"brazil":203553000

}

}

EOF


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

}

}

EOF

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.


71

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


{

"hello":"world"

}

EOF

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


72

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


73

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

}


74

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-





75


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:


76



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




77

HTTP/1.1200OK



etag:"_WQ47YHa--_"


showresponsebodyUnknowndocumenthandle:


HTTP/1.1404NotFound



showresponsebodyRevisionconflict:

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





etag:"_WQ47YFK--_"

showresponsebody


Thisvariantisnewin3.0.NotethatitrequiresabodyintheDELETErequest.


78

HTTPInterfaceforEdgesThisisanintroductiontoArangoDB'sRESTinterfaceforedges.

ArangoDBoffersgraphfunctionality;Edgesareonepartofthat.

Edges

79

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

80

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

81

"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

82

}

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

83

GeneralGraphsThischapterdescribestheRESTinterfaceforthemulti-collectiongraphmodule.Itallowsyoutodefineagraphthatisspreadacrossseveraledgeanddocumentcollections.Thereisnoneedtoincludethereferencedcollectionswithinthequery,thismodulewillhandleitforyou.

GeneralGraph

84

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

85


"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

86

],

"to":[

"endVertices"

]

}

]

}

EOF

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"

}

}

EOF

HTTP/1.1202Accepted



etag:_WQ47PHG--_

{

"error":false,

"graph":{

Management

87

"name":"myGraph",

"edgeDefinitions":[

{


"from":[

"startVertices"

],

"to":[

"endVertices"

]

}

],


"isSmart":false,

"numberOfShards":0,




"_rev":"_WQ47PHG--_"

},

"code":202

}


{

"name":"myGraph",

"edgeDefinitions":[

{


"from":[

"startVertices"

],

"to":[

"endVertices"

]

}

]

}

EOF

HTTP/1.1202Accepted



etag:_WQ47OnC--_

showresponsebody


{

"name":"myGraph",

"edgeDefinitions":[

{


"from":[

"startVertices"

],

"to":[

"endVertices"

]

}

Management

88

],

"isSmart":true,

"options":{

"numberOfShards":9,

"smartGraphAttribute":"region"

}

}

EOF

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

89

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

90

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"

}

EOF

Management

91

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"

}

EOF

HTTP/1.1202Accepted



etag:_WQ47N8y--_

showresponsebody

Removevertexcollection

Removeavertexcollectionformthegraph.

Management

92

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

93

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

94


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"

]

}

EOF

HTTP/1.1202Accepted



etag:_WQ47Mr6--_

{

"error":false,

"graph":{

"name":"social",

"edgeDefinitions":[

{


"from":[

"female",

"male"

Management

95

],

"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"

]

}

EOF

HTTP/1.1202Accepted



etag:_WQ47Mr6--_

showresponsebody

Replaceanedgedefinition

Management

96

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"

]

}

EOF

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

97

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"

]

}

EOF

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

98




"_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

99

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"

}

EOF

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

100

EOF

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

101

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

}

EOF

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

102


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

{

"age":26

}

EOF

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

}

EOF

HTTP/1.1202Accepted



etag:_WQ47TpK--_

{

"error":false,

"vertex":{


"_key":"alice",

"_rev":"_WQ47TpK--_",

"_oldRev":"_WQ47Toy--B"

},

"code":202

}

PathParameters


QueryParameters


HeaderParameters


Vertices

103



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

}

EOF

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

104


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

105

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"

}

EOF

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


Edges

106

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

{

"type":"friend",


"_to":"female/diana"

}

EOF

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.

Edges

107

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"

}

EOF

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

Edges

108

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

Examples


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

{

"since":"01.01.2001"

}

EOF

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"

}

EOF

HTTP/1.1202Accepted



etag:_WQ47SvK--_

{

"error":false,

"edge":{


"_key":"9340",

"_rev":"_WQ47SvK--_",

"_oldRev":"_WQ47SvC--H"

},

"code":202

}

PathParameters


QueryParameters

Edges

109


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"

}

EOF

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

Edges

110


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

Edges

111

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

112

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"

}

EOF

HTTP/1.1200OK



{

"result":{

"visited":{

"vertices":[

{

"_key":"alice",

"_id":"persons/alice",

"_rev":"_WQ47gHO--B",

"name":"Alice"

},

{

Traversals

113

"_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

114

{

"_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

115

{



"direction":"inbound"

}

EOF

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

116

Example:Followanydirectionofedges


{



"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"global"

}

}

EOF

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

117

"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

118

"_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

119

"_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;"

}

EOF

HTTP/1.1200OK



{

Traversals

120

"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

121

Example:DonotfollowedgesfromBob


{




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

}

EOF

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

122

},

"error":false,

"code":200

}

Example:Visitonlynodesinadepthofatleast2


{




"minDepth":2

}

EOF

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

123

{

"_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

}

EOF

HTTP/1.1200OK



Traversals

124

{

"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

125

}

EOF

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);"

}

EOF

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

126

"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;"

}

EOF

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

127

"_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"

}

EOF

HTTP/1.1200OK

Traversals

128



{

"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

129

"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

130

{

"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

131

"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

132

{

"_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

133

{

"_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

134

"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

135


"direction":"any",

"order":"postorder"

}

EOF

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

136



"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

137

"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

138

"_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

139


"_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

140

"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

141

"_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

142

Usingbackwarditem-ordering:


{



"direction":"any",

"itemOrder":"backward"

}

EOF

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

143


"_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

144

"_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

145

},

{

"_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

146


"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

147

"_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

148

},

{

"_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

149

}

Example:Edgesshouldonlybeincludedonceglobally,butnodesareincludedeverytimetheyarevisited


{



"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"global"

}

}

EOF

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

150

}

]

},

{

"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

151

"_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

152

"_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

153

"uniqueness":{

"vertices":"none",

"edges":"none"

},

"maxIterations":5

}

EOF

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"

}

EOF

HTTP/1.1200OK



showresponsebodyFollowonlyinboundedges


{



"direction":"inbound"

}

EOF

Traversals

154

HTTP/1.1200OK



showresponsebodyFollowanydirectionofedges


{



"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"global"

}

}

EOF

HTTP/1.1200OK



showresponsebodyExcludingCharlieandBob


{




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

\"exclude\";}return;"

}

EOF

HTTP/1.1200OK



showresponsebodyDonotfollowedgesfromBob


{




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

}

EOF

Traversals

155

HTTP/1.1200OK



showresponsebodyVisitonlynodesinadepthofatleast2


{




"minDepth":2

}

EOF

HTTP/1.1200OK



showresponsebodyVisitonlynodesinadepthofatmost1


{




"maxDepth":1

}

EOF

HTTP/1.1200OK



showresponsebodyUsingavisitorfunctiontoreturnvertexidsonly


{




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

}

EOF

HTTP/1.1200OK



Traversals

156

showresponsebodyCountallvisitednodesandreturnalistofnodesonly


{




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

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

}

EOF

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;"

}

EOF

HTTP/1.1200OK



showresponsebodyFollowthedepthfirststrategy


{



"direction":"any",

"strategy":"depthfirst"

}

EOF

HTTP/1.1200OK



Traversals

157

showresponsebodyUsingpostorderordering


{



"direction":"any",

"order":"postorder"

}

EOF

HTTP/1.1200OK



showresponsebodyUsingbackwarditem-ordering:


{



"direction":"any",

"itemOrder":"backward"

}

EOF

HTTP/1.1200OK



showresponsebodyEdgesshouldonlybeincludedonceglobally,butnodesareincludedeverytimetheyarevisited


{



"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"global"

}

}

EOF

HTTP/1.1200OK



Traversals

158

showresponsebodyIftheunderlyinggraphiscyclic,maxIterationsshouldbesetTheunderlyinggraphhastwoverticesAliceandBob.Withthedirectededges:

AliceknowsBobBobknowsAlice


{



"direction":"any",

"uniqueness":{

"vertices":"none",

"edges":"none"

},

"maxIterations":5

}

EOF




showresponsebodyAllexampleswereusingthisgraph:

Traversals

159

HTTPInterfaceforAQLQueryCursors

DatabaseCursors

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

Toexecuteaquery,thequerydetailsneedtobeshippedfromtheclienttotheserverviaanHTTPPOSTrequest.

AQLQueryCursors

160

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

161

"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

162

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

163

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

164

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

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"10541",


"_rev":"_WQ47Xre--B",

"hello2":"world1"

AccessingCursors

165

},

{

"_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

}

EOF

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

166

},

"warnings":[]

},

"cached":false

}

Example:Usingthequeryoption"fullCount"


{

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

"count":true,

"options":{

"fullCount":true

}

}

EOF

HTTP/1.1201Created



{

"result":[

501,

502,

503,

504,

505,

506,

507,

508,

509,

510

],

"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

167

"rules":[

"-all",

"+remove-unnecessary-filters"

]

}

}

}

EOF

HTTP/1.1201Created



{

"result":[

1,

2,

3,

4,

5,

6,

7,

8,

9,

10

],

"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"

}

EOF

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

168

},

"warnings":[]

},

"error":false,

"code":201

}

Example:Executeadata-modificationquerywithoptionignoreErrors


{

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

}

EOF

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

169

"query":"FORuINunknowncollLIMIT2RETURNu",

"count":true,

"batchSize":2

}

EOF

HTTP/1.1404NotFound



{

"error":true,

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

"code":404,

"errorNum":1203

}

Example:Badquery-Executeadata-modificationquerythatattemptstoremoveanon-existingdocument


{

"query":"REMOVE'foo'INproducts"

}

EOF

HTTP/1.1404NotFound



{

"error":true,

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

"code":404,

"errorNum":1202

}


{


"count":true,

"batchSize":2

}

EOF

HTTP/1.1201Created



showresponsebodyExecuteaqueryandextractapartoftheresult


{


"count":true,

"batchSize":2

}

EOF

AccessingCursors

170

HTTP/1.1201Created



showresponsebodyUsingthequeryoption"fullCount"


{

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

"count":true,

"options":{

"fullCount":true

}

}

EOF

HTTP/1.1201Created



showresponsebodyEnablinganddisablingoptimizerrules


{

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

"count":true,

"options":{

"maxPlans":1,

"optimizer":{

"rules":[

"-all",

"+remove-unnecessary-filters"

]

}

}

}

EOF

HTTP/1.1201Created



showresponsebodyExecuteadata-modificationqueryandretrievethenumberofmodifieddocuments


{

"query":"FORpINproductsREMOVEpINproducts"

}

EOF

AccessingCursors

171

HTTP/1.1201Created



showresponsebodyExecuteadata-modificationquerywithoptionignoreErrors


{

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

}

EOF

HTTP/1.1201Created



showresponsebodyBadquery-Missingbody

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




showresponsebodyBadquery-Unknowncollection


{

"query":"FORuINunknowncollLIMIT2RETURNu",

"count":true,

"batchSize":2

}

EOF

HTTP/1.1404NotFound



showresponsebodyBadquery-Executeadata-modificationquerythatattemptstoremoveanon-existingdocument


{

"query":"REMOVE'foo'INproducts"

}

EOF

AccessingCursors

172

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

}

EOF

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

173

"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

}

EOF

AccessingCursors

174


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

}

EOF

HTTP/1.1201Created



AccessingCursors

175

{

"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

}

EOF

HTTP/1.1201Created



showresponsebody

AccessingCursors

176

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

177

Validquery

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

{

"query":"FORpINproductsRETURNp"

}

EOF

HTTP/1.1200OK



{

"plan":{

"nodes":[

{

"type":"SingletonNode",

"dependencies":[],

"id":1,

"estimatedCost":1,

"estimatedNrItems":1

},

{

"type":"EnumerateCollectionNode",

"dependencies":[

1

],

"id":2,

"estimatedCost":12,

"estimatedNrItems":10,

"database":"_system",


"random":false,

"satellite":false,

"outVariable":{

"id":0,

"name":"p"

}

},

{

"type":"ReturnNode",

"dependencies":[

2

],

"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

178

"plansCreated":1

},

"error":false,

"code":200

}

Example:Aplanwithsomeoptimizerrulesapplied


{

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

}

EOF

HTTP/1.1200OK



{

"plan":{

"nodes":[

{


"dependencies":[],

"id":1,

"estimatedCost":1,


},

{

"type":"IndexNode",

"dependencies":[

1

],

"id":11,

"estimatedCost":4.321928094887362,




"satellite":false,

"outVariable":{

"id":0,

"name":"p"

},

"indexes":[

{

"id":"11343",

"type":"skiplist",

"fields":[

"id"

],

"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

179

"name":"p",

"id":0

}

]

},

{

"type":"value",

"value":4

}

]

}

]

}

]

},

"reverse":false

},

{

"type":"CalculationNode",

"dependencies":[

11

],

"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":[

4

],

"id":5,

"estimatedCost":6.321928094887362,


"inVariable":{

"id":4,

"name":"3"

}

},

{

"type":"LimitNode",

"dependencies":[

5

],

"id":9,

"estimatedCost":7.321928094887362,


"offset":0,

"limit":1,

"fullCount":false

AQLQueries

180

},

{


"dependencies":[

9

],

"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":[

6

],

"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

181

"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"

]

}

}

}

EOF

HTTP/1.1200OK



{

"plans":[

{

"nodes":[

{


"dependencies":[],

"id":1,

"estimatedCost":1,


},

{

"type":"IndexNode",

"dependencies":[

1

],

"id":11,

"estimatedCost":11,




"satellite":false,

"outVariable":{

"id":0,

"name":"p"

},

"indexes":[

{

"id":"11389",

AQLQueries

182

"type":"skiplist",

"fields":[

"id"

],

"unique":false,

"sparse":false,

"deduplicate":true

}

],

"condition":{

},

"reverse":false

},

{


"dependencies":[

11

],

"id":3,

"estimatedCost":21,


"expression":{


"name":"id",

"subNodes":[

{

"type":"reference",

"name":"p",

"id":0

}

]

},

"outVariable":{

"id":1,

"name":"a"

},

"canThrow":false,


},

{


"dependencies":[

3

],

"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":[

4

],

"id":5,

"estimatedCost":41,


AQLQueries

183

"inVariable":{

"id":4,

"name":"3"

}

},

{


"dependencies":[

5

],

"id":6,

"estimatedCost":51,


"expression":{


"name":"name",

"subNodes":[

{

"type":"reference",

"name":"p",

"id":0

}

]

},

"outVariable":{

"id":2,

"name":"name"

},

"canThrow":false,


},

{


"dependencies":[

6

],

"id":7,

"estimatedCost":61,


"expression":{


"name":"id",

"subNodes":[

{

"type":"reference",

"name":"p",

"id":0

}

]

},

"outVariable":{

"id":6,

"name":"5"

},

"canThrow":false,


},

{

"type":"LimitNode",

"dependencies":[

7

],

"id":9,

"estimatedCost":62,


"offset":0,

"limit":1,

"fullCount":false

},

{


"dependencies":[

9

],

"id":10,

"estimatedCost":63,

AQLQueries

184


"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

}

}

EOF

HTTP/1.1200OK



{

"plans":[

AQLQueries

185

{

"nodes":[

{


"dependencies":[],

"id":1,

"estimatedCost":1,


},

{

"type":"IndexNode",

"dependencies":[

1

],

"id":6,

"estimatedCost":1.99,




"satellite":false,

"outVariable":{

"id":0,

"name":"p"

},

"indexes":[

{

"id":"11305",

"type":"hash",

"fields":[

"id"

],

"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":[

6

],

"id":5,


AQLQueries

186


"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"

}

EOF

HTTP/1.1200OK



{

"plan":{

"nodes":[

{


"dependencies":[],

"id":1,

"estimatedCost":1,


},

{


"dependencies":[

1

],

AQLQueries

187

"id":2,

"estimatedCost":2,


"expression":{

"type":"range",

"subNodes":[

{

"type":"value",

"value":1

},

{

"type":"value",

"value":10

}

]

},

"outVariable":{

"id":2,

"name":"1"

},

"canThrow":false,


},

{


"dependencies":[

2

],

"id":4,

"estimatedCost":3,


"expression":{

"type":"value",

"value":null

},

"outVariable":{

"id":4,

"name":"3"

},

"canThrow":false,

"expressionType":"json"

},

{

"type":"EnumerateListNode",

"dependencies":[

4

],

"id":3,

"estimatedCost":13,


"inVariable":{

"id":2,

"name":"1"

},

"outVariable":{

"id":0,

"name":"i"

}

},

{


"dependencies":[

3

],

"id":5,

"estimatedCost":23,


"inVariable":{

"id":4,

"name":"3"

}

}

],

"rules":[


"move-calculations-up-2"

AQLQueries

188

],

"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":"[email protected]"

}

EOF




{

"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

189

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

EOF

HTTP/1.1200OK



{

"plan":{

"nodes":[

{


"dependencies":[],

"id":1,

"estimatedCost":1,


},

{


"dependencies":[

1

],

"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":[

2

],

"id":7,



},

{

"type":"EnumerateListNode",

"dependencies":[

7

],

"id":3,



"inVariable":{

"id":2,

"name":"1"

},

"outVariable":{

"id":0,

"name":"i"

}

},

{

AQLQueries

190


"dependencies":[

3

],

"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"

}

EOF

HTTP/1.1200OK



showresponsebodyAplanwithsomeoptimizerrulesapplied


{

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

LIMIT1RETURNname"

AQLQueries

191

}

EOF

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"

]

}

}

}

EOF

HTTP/1.1200OK



showresponsebodyReturningallplans


{

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

"options":{

"allPlans":true

}

}

EOF

HTTP/1.1200OK



showresponsebodyAquerythatproducesawarning


AQLQueries

192

{

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

}

EOF

HTTP/1.1200OK



showresponsebodyInvalidquery(missingbindparameter)


{

"query":"[email protected]"

}

EOF




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


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

EOF

HTTP/1.1200OK



showresponsebody

ParseanAQLquery

parseanAQLqueryandreturninformationaboutit

POST/_api/query

Thisendpointisforqueryvalidationonly.Toactuallyquerythedatabase,see/api/cursor.


query:Tovalidateaquerystringwithoutexecutingit,thequerystringcanbepassedtotheserverviaanHTTPPOSTrequest.

Example:aValidquery

AQLQueries

193

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

{"query":"[email protected]"}

EOF

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

194

"subNodes":[

{


"name":"n",

"subNodes":[

{

"type":"reference",

"name":"p",

"id":0

}

]

}

]

}

]

}

]

}

Example:anInvalidquery



EOF




{

"error":true,

"errorMessage":"syntaxerror,unexpectedassignmentnear'[email protected]'atposition1:33",

"code":400,

"errorNum":1501

}

ReturnCodes

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

Examples

aValidquery



EOF

HTTP/1.1200OK



showresponsebodyanInvalidquery

AQLQueries

195



EOF




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

196

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

197

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

198

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

199

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;}"

}

EOF

HTTP/1.1201Created



{

"error":false,

"code":201

}

ReturnCodes


200

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

Examples

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

{



}

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


201

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


202

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



[

{



}

]


203

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}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12142",


"_rev":"_WQ47fae--_",

"Hello1":"World1"

},

{

"_key":"12155",

SimpleQueries

204


"_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}

EOF

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

205

"warnings":[]

},

"cached":false

}

ReturnCodes

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

Examples

Limittheamountofdocumentsusinglimit


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

EOF

HTTP/1.1201Created



showresponsebodyUsingabatchSizevalue


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

EOF

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

206

Matchinganattribute

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

{


"example":{

"i":1

}

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12208",


"_rev":"_WQ47fbm--_",

"a":{

"k":2,

"j":2

},

"i":1

},

{

"_key":"12202",


"_rev":"_WQ47fbi--B",

"a":{

"j":1

},

"i":1

},

{

"_key":"12198",


"_rev":"_WQ47fbi--_",

"a":{

"k":1,

"j":1

},

"i":1

},

{

"_key":"12205",


"_rev":"_WQ47fbi--D",

"i":1

}

],

"hasMore":false,

"count":4,

"error":false,

"code":201

}

Example:Matchinganattributewhichisasub-document


{


"example":{

"a.j":1

}

}

EOF

SimpleQueries

207

HTTP/1.1201Created



{

"result":[

{

"_key":"12228",


"_rev":"_WQ47fcK--B",

"a":{

"j":1

},

"i":1

},

{

"_key":"12224",


"_rev":"_WQ47fcK--_",

"a":{

"k":1,

"j":1

},

"i":1

}

],

"hasMore":false,

"count":2,

"error":false,

"code":201

}

Example:Matchinganattributewithinasub-document


{


"example":{

"a":{

"j":1

}

}

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12254",


"_rev":"_WQ47fcq--B",

"a":{

"j":1

},

"i":1

}

],

"hasMore":false,

"count":1,

"error":false,

"code":201

}

ReturnCodes

SimpleQueries

208


Examples

Matchinganattribute

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

<<EOF

{


"example":{

"i":1

}

}

EOF

HTTP/1.1201Created



showresponsebodyMatchinganattributewhichisasub-document


<<EOF

{


"example":{

"a.j":1

}

}

EOF

HTTP/1.1201Created



showresponsebodyMatchinganattributewithinasub-document


<<EOF

{


"example":{

"a":{

"j":1

}

}

}

EOF

SimpleQueries

209

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":{

"i":1

}

}

EOF

HTTP/1.1200OK



{

"document":{

"_key":"12286",


"_rev":"_WQ47fdO--F",

"a":{

"k":2,

"j":2

},

"i":1

},

"error":false,

"code":200

}

Example:Ifnodocumentwasfound


{

SimpleQueries

210


"example":{

"l":1

}

}

EOF

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":{

"i":1

}

}

EOF

HTTP/1.1200OK



showresponsebodyIfnodocumentwasfound


example<<EOF

{


"example":{

"l":1

}

}

EOF

HTTP/1.1404NotFound



SimpleQueries

211

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"

}

EOF

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

212

"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",

"baz"

],

"collection":"test"

}

EOF

HTTP/1.1200OK



{

"documents":[],

"error":false,

"code":200

}

ReturnCodes

200:isreturnediftheoperationwascarriedoutsuccessfully.

SimpleQueries

213

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"

}

EOF

HTTP/1.1200OK



showresponsebodyLookingupnon-existingdocuments

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

keys<<EOF

{

"keys":[

"foo",

"bar",

"baz"

],

"collection":"test"

}

EOF

HTTP/1.1200OK



showresponsebody

Returnarandomdocument

returnsarandomdocumentfromacollection

SimpleQueries

214

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

{


}

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

{


}

EOF

HTTP/1.1200OK



showresponsebody

Removedocumentsbytheirkeys

removesmultipledocumentsbytheirkeys

PUT/_api/simple/remove-by-keys


keys(string):arraywiththe_keysofdocumentstoremove.options:

SimpleQueries

215

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"

}

EOF

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",

"baz"

],

"collection":"test"

}

EOF

HTTP/1.1200OK



{

SimpleQueries

216

"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"

}

EOF

HTTP/1.1200OK



showresponsebody


keys<<EOF

{

"keys":[

"foo",

"bar",

"baz"

],

"collection":"test"

}

EOF

HTTP/1.1200OK



showresponsebody

Removedocumentsbyexample

removesalldocumentsofacollectionthatmatchanexample

PUT/_api/simple/remove-by-example


SimpleQueries

217

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":{

"a":{

"j":1

}

}

}

EOF

HTTP/1.1200OK



{

"deleted":1,

"error":false,

"code":200

}

Example:UsingParameter:waitForSyncandlimit


{


"example":{

"a":{

"j":1

}

},

"waitForSync":true,

"limit":2

}

EOF

HTTP/1.1200OK



{

"deleted":1,

"error":false,

"code":200

}

SimpleQueries

218

Example:UsingParameter:waitForSyncandlimitwithnewsignature


{


"example":{

"a":{

"j":1

}

},

"options":{

"waitForSync":true,

"limit":2

}

}

EOF

HTTP/1.1200OK



{

"deleted":1,

"error":false,

"code":200

}


example<<EOF

{


"example":{

"a":{

"j":1

}

}

}

EOF

HTTP/1.1200OK



showresponsebodyUsingParameter:waitForSyncandlimit


example<<EOF

{


"example":{

"a":{

"j":1

}

},

"waitForSync":true,

"limit":2

}

SimpleQueries

219

EOF

HTTP/1.1200OK



showresponsebodyUsingParameter:waitForSyncandlimitwithnewsignature


example<<EOF

{


"example":{

"a":{

"j":1

}

},

"options":{

"waitForSync":true,

"limit":2

}

}

EOF

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

220

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

{


"example":{

"a":{

"j":1

}

},

"newValue":{

"foo":"bar"

},

"limit":3

}

EOF

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":{

"a":{

"j":1

}

},

"newValue":{

"foo":"bar"

},

"options":{

"limit":3,

"waitForSync":true

}

}

EOF

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":{

"a":{

"j":1

}

},

SimpleQueries

221

"newValue":{

"foo":"bar"

},

"limit":3

}

EOF

HTTP/1.1200OK



showresponsebodyUsingnewSignatureforattributesWaitForSyncandlimit

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

example<<EOF

{


"example":{

"a":{

"j":1

}

},

"newValue":{

"foo":"bar"

},

"options":{

"limit":3,

"waitForSync":true

}

}

EOF

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

222

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":{

"a":{

"j":1

}

},

"newValue":{

"a":{

"j":22

}

},

"limit":3

}

EOF

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":{

"a":{

"j":1

}

},

"newValue":{

"a":{

"j":22

}

},

"options":{

"limit":3,

"waitForSync":true

}

SimpleQueries

223

}

EOF

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":{

"a":{

"j":1

}

},

"newValue":{

"a":{

"j":22

}

},

"limit":3

}

EOF

HTTP/1.1200OK



showresponsebodyusingnewsignatureforoptions

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

example<<EOF

{


"example":{

"a":{

"j":1

}

},

"newValue":{

"a":{

"j":22

}

},

"options":{

"limit":3,

"waitForSync":true

}

}

SimpleQueries

224

EOF

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

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12528",


"_rev":"_WQ47fie--B",

"i":2

},

{

"_key":"12531",


"_rev":"_WQ47fie--D",

SimpleQueries

225

"i":3

}

],

"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

}

EOF

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

226

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

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12441",


"_rev":"_WQ47fgq--D",

"name":"Name/0.002/",

"loc":[

0.002,

0

]

},

{

"_key":"12435",


"_rev":"_WQ47fgq--_",

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

"loc":[

-0.002,

0

]

}

],

"hasMore":false,

"count":2,

"error":false,

"code":201

}

Example:Withdistance


{


"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

"distance":"distance"

}

SimpleQueries

227

EOF

HTTP/1.1201Created



{

"result":[

{

"distance":222.38985328911744,


"_key":"12486",

"_rev":"_WQ47fhq--D",

"loc":[

-0.002,

0

],

"name":"Name/-0.002/"

},

{

"distance":222.38985328911744,


"_key":"12492",

"_rev":"_WQ47fhq--H",

"loc":[

0.002,

0

],

"name":"Name/0.002/"

},

{

"distance":444.779706578235,


"_key":"12483",

"_rev":"_WQ47fhq--B",

"loc":[

-0.004,

0

],

"name":"Name/-0.004/"

}

],

"hasMore":false,

"count":3,

"error":false,

"code":201

}

ReturnCodes


Examples

Withoutdistance


{


"latitude":0,

"longitude":0,

"skip":1,

"limit":2

}

EOF

SimpleQueries

228

HTTP/1.1201Created



showresponsebodyWithdistance


{


"latitude":0,

"longitude":0,

"skip":1,

"limit":3,


}

EOF

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

229



{


"latitude":0,

"longitude":0,

"skip":1,

"limit":2,

"radius":500

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12854",


"_rev":"_WQ47foi--_",

"name":"Name/0.002/",

"loc":[

0.002,

0

]

},

{

"_key":"12848",


"_rev":"_WQ47foe--H",

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

"loc":[

-0.002,

0

]

}

],

"hasMore":false,

"count":2,

"error":false,

"code":201

}



{


"latitude":0,

"longitude":0,

"skip":1,

"limit":3,

"distance":"distance",

"radius":300

}

EOF

HTTP/1.1201Created



{

"result":[

SimpleQueries

230

{

"distance":222.38985328911744,


"_key":"12899",

"_rev":"_WQ47fpW--B",

"loc":[

-0.002,

0

],

"name":"Name/-0.002/"

},

{

"distance":222.38985328911744,


"_key":"12905",

"_rev":"_WQ47fpW--F",

"loc":[

0.002,

0

],


},

{

"distance":444.779706578235,


"_key":"12896",

"_rev":"_WQ47fpW--_",

"loc":[

-0.004,

0

],

"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

}

EOF

HTTP/1.1201Created



SimpleQueries

231



{


"latitude":0,

"longitude":0,

"skip":1,

"limit":3,


"radius":300

}

EOF

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

}

EOF

SimpleQueries

232

HTTP/1.1201Created



{

"result":[

{

"_key":"12965",


"_rev":"_WQ47fqO--F",

"name":"Name/0.008/",

"loc":[

0.008,

0

]

},

{

"_key":"12962",


"_rev":"_WQ47fqO--D",

"name":"Name/0.006/",

"loc":[

0.006,

0

]

}

],

"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

}

EOF

HTTP/1.1201Created



showresponsebody

Fulltextindexquery

returnsdocumentsofacollectionasaresultofafulltextquery

SimpleQueries

233

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"

}

EOF

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

234

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

<<EOF

{


"attribute":"text",

"query":"word"

}

EOF

HTTP/1.1201Created



showresponsebody

SimpleQueries

235

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

236

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

237

"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"

}

EOF

HTTP/1.1202Accepted







AsyncResultHandling

238



{

"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

239

FetchingtheresultofanHTTPPOSTjobthatfailed:

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

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

{

"name":"thisnameisinvalid"

}

EOF

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"

}

EOF

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

240

{

"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"

}

EOF

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

241

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

242


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

243

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

244


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);}"

}

EOF

HTTP/1.1202Accepted




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

HTTP/1.1204NoContent


AsyncResultHandling

245


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"

]

},


}

EOF

HTTP/1.1202Accepted




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




Returnslistofasyncjobs

AsyncResultHandling

246

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

247

"read":[

"_frontend"

]

},


}

EOF

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

248





HTTP/1.1200OK



[]

Queryingthestatusofapendingjob:(wecreateasleepjobtherefore...)


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

{

"collections":{

"read":[

"_frontend"

]

},


}

EOF

HTTP/1.1202Accepted





HTTP/1.1200OK



[

"151690759883053"

]


HTTP/1.1200OK



{

"result":true

}

AsyncResultHandling

249

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

250

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"]

EOF

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"]

EOF

HTTP/1.1201Created



{

"error":false,

"created":2,

"errors":0,

"empty":0,

BulkImport/Export

251

"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"]

EOF

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"]

EOF

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

252

["abc",25,"test"]

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

EOF

HTTP/1.1409Conflict



{

"error":true,

"errorMessage":"uniqueconstraintviolated",

"code":409,

"errorNum":1210

}

Example:Usinganon-existingcollection



["abc",25,"test"]

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

EOF

HTTP/1.1404NotFound



{

"error":true,


"code":404,

"errorNum":1203

}

Example:Usingamalformedbody


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

EOF




{

"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

253

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"]

EOF

HTTP/1.1201Created



showresponsebodyImportingintoanedgecollection,withattributes_from,_toandname


collection=links<<EOF

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

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

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

EOF

HTTP/1.1201Created



showresponsebodyImportingintoanedgecollection,omitting_fromor_to


collection=links&details=true<<EOF

["name"]

["somename"]

["othername"]

EOF

HTTP/1.1201Created



showresponsebodyViolatingauniqueconstraint,butallowpartialimports


collection=products&details=true<<EOF


["abc",25,"test"]

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

EOF

BulkImport/Export

254

HTTP/1.1201Created



showresponsebodyViolatingauniqueconstraint,notallowingpartialimports


collection=products&complete=true<<EOF


["abc",25,"test"]

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

EOF

HTTP/1.1409Conflict



showresponsebodyUsinganon-existingcollection




["abc",25,"test"]

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

EOF

HTTP/1.1404NotFound



showresponsebodyUsingamalformedbody



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

EOF




showresponsebody

importsdocumentsfromJSON

importsdocumentsfromJSON

POST/_api/import#json

BulkImport/Export

255


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

256

"value2":"test",

"allowed":true

},

{

"_key":"foo",

"name":"baz"

},

{

"name":{

"detailed":"detailedname",

"short":"shortname"

}

}

]

EOF

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"}}

EOF

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

257

"name":"baz"

},

{

"name":{


"short":"shortname"

}

}

]

EOF

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"}

EOF

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"

}

]

EOF

HTTP/1.1201Created



{

"error":false,

"created":0,

"errors":1,

"empty":0,

"updated":0,

BulkImport/Export

258

"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

<<EOF

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

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

EOF

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



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"}

EOF

HTTP/1.1404NotFound


BulkImport/Export

259


{

"error":true,


"code":404,

"errorNum":1203

}

Example:Usingamalformedbody

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

{}

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

260

EOF

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"}}

EOF

HTTP/1.1201Created



showresponsebodyUsingtheautotypedetection


collection=products&type=auto<<EOF

[

{

"_key":"abc",

"value1":25,

"value2":"test",

"allowed":true

},

{

"_key":"foo",

"name":"baz"

},

{

"name":{


"short":"shortname"

}

}

]

EOF

HTTP/1.1201Created



showresponsebody

BulkImport/Export

261

Importingintoanedgecollection,withattributes_from,_toandname


collection=links&type=documents<<EOF

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

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

EOF

HTTP/1.1201Created



showresponsebodyImportingintoanedgecollection,omitting_fromor_to


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

[

{

"name":"somename"

}

]

EOF

HTTP/1.1201Created



showresponsebodyViolatingauniqueconstraint,butallowpartialimports


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



EOF

HTTP/1.1201Created



showresponsebodyViolatingauniqueconstraint,notallowingpartialimports


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



EOF

HTTP/1.1409Conflict


BulkImport/Export

262


showresponsebodyUsinganon-existingcollection


collection=products&type=documents<<EOF

{"name":"test"}

EOF

HTTP/1.1404NotFound



showresponsebodyUsingamalformedbody


collection=products&type=list<<EOF

{}

EOF




showresponsebody

BulkImport/Export

263

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

264

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

265

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

266

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

267

{"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

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

268

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--

EOF

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

269

{\"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

270


EOF

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

<<EOF

--SomeBoundaryValue


Content-Id:myId1

GET/_api/versionHTTP/1.1

--SomeBoundaryValue


Content-Id:myId2


--SomeBoundaryValue


Content-Id:someId

BatchRequests

271

POST/_api/collection/productsHTTP/1.1

{"name":"products"}

--SomeBoundaryValue


Content-Id:nextId

GET/_api/collection/products/figuresHTTP/1.1

--SomeBoundaryValue


Content-Id:otherId



EOF

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

272

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


EOF

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

273

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

274

id:idoftemporarycursorcreatedontheserver(optional,seeabove)

IftheJSONrepresentationismalformedorthequeryspecificationismissingfromtherequest,theserverwillrespondwithHTTP400.






Clientsshouldalwaysdeleteanexportcursorresultasearlyaspossiblebecausealingeringexportcursorwillpreventtheunderlyingcollectionfrombeingcompactedorunloaded.Bydefault,unusedcursorswillbedeletedautomaticallyafteraserver-definedidletime,andclientscanadjustthisidletimebysettingthettlvalue.

Note:thisAPIiscurrentlynotsupportedonclustercoordinators.

Exportingdata

275

HTTPInterfaceforIndexes

Indexes

ThisisanintroductiontoArangoDB'sHTTPinterfaceforindexesingeneral.Therearespecialsectionsforvariousindextypes.

Index

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

276

AllindexesinArangoDBhaveanuniquehandle.ThisindexhandleidentifiesanindexandismanagedbyArangoDB.AllindexesarefoundundertheURI

http://server:port/_api/index/index-handle

Forexample:Assumethattheindexhandleisdemo/63563528thentheURLofthatindexis:

http://localhost:8529/_api/index/demo/63563528

Indexes

277

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

278

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

279


{

"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

280



"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

281

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":[

"a",

"b"

]

}

EOF

HTTP/1.1201Created



{

"deduplicate":true,

"fields":[

"a",

"b"

],


"isNewlyCreated":true,


"sparse":false,

"type":"hash",

Hash

282

"unique":true,

"error":false,

"code":201

}

Example:Creatinganon-uniquehashindex


{

"type":"hash",

"unique":false,

"fields":[

"a",

"b"

]

}

EOF

HTTP/1.1201Created



{

"deduplicate":true,

"fields":[

"a",

"b"

],




"sparse":false,

"type":"hash",

"unique":false,

"error":false,

"code":201

}

Example:Creatingasparseindex


{

"type":"hash",

"unique":false,

"sparse":true,

"fields":[

"a"

]

}

EOF

HTTP/1.1201Created



{

"deduplicate":true,

"fields":[

"a"

],




"sparse":true,

Hash

283

"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":[

"a",

"b"

]

}

EOF

HTTP/1.1201Created



showresponsebodyCreatinganon-uniquehashindex



{

"type":"hash",

"unique":false,

"fields":[

"a",

"b"

]

}

EOF

HTTP/1.1201Created



showresponsebodyCreatingasparseindex

Hash

284



{

"type":"hash",

"unique":false,

"sparse":true,

"fields":[

"a"

]

}

EOF

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":{

"i":1

}

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12208",


"_rev":"_WQ47fbm--_",

"a":{

"k":2,

Hash

285

"j":2

},

"i":1

},

{

"_key":"12202",


"_rev":"_WQ47fbi--B",

"a":{

"j":1

},

"i":1

},

{

"_key":"12198",


"_rev":"_WQ47fbi--_",

"a":{

"k":1,

"j":1

},

"i":1

},

{

"_key":"12205",


"_rev":"_WQ47fbi--D",

"i":1

}

],

"hasMore":false,

"count":4,

"error":false,

"code":201

}

Example:Matchinganattributewhichisasub-document


{


"example":{

"a.j":1

}

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12228",


"_rev":"_WQ47fcK--B",

"a":{

"j":1

},

"i":1

},

{

"_key":"12224",


"_rev":"_WQ47fcK--_",

"a":{

"k":1,

"j":1

},

Hash

286

"i":1

}

],

"hasMore":false,

"count":2,

"error":false,

"code":201

}

Example:Matchinganattributewithinasub-document


{


"example":{

"a":{

"j":1

}

}

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12254",


"_rev":"_WQ47fcq--B",

"a":{

"j":1

},

"i":1

}

],

"hasMore":false,

"count":1,

"error":false,

"code":201

}

ReturnCodes


Examples

Matchinganattribute


<<EOF

{


"example":{

"i":1

}

}

EOF

Hash

287

HTTP/1.1201Created



showresponsebodyMatchinganattributewhichisasub-document


<<EOF

{


"example":{

"a.j":1

}

}

EOF

HTTP/1.1201Created



showresponsebodyMatchinganattributewithinasub-document


<<EOF

{


"example":{

"a":{

"j":1

}

}

}

EOF

HTTP/1.1201Created



showresponsebody

Finddocumentsmatchinganexample

returnsonedocumentofacollectionmatchingagivenexample

PUT/_api/simple/first-example


example:Theexampledocument.collection:Thenameofthecollectiontoquery.

Hash

288

Thiswillreturnthefirstdocumentmatchingagivenexample.

ReturnsaresultcontainingthedocumentorHTTP404ifnodocumentmatchedtheexample.

Ifmorethanonedocumentinthecollectionmatchesthespecifiedexample,onlyoneofthesedocumentswillbereturned,anditisundefinedwhichofthematchingdocumentsisreturned.

Example:Ifamatchingdocumentwasfound


{


"example":{

"i":1

}

}

EOF

HTTP/1.1200OK



{

"document":{

"_key":"12286",


"_rev":"_WQ47fdO--F",

"a":{

"k":2,

"j":2

},

"i":1

},

"error":false,

"code":200

}

Example:Ifnodocumentwasfound


{


"example":{

"l":1

}

}

EOF

HTTP/1.1404NotFound



{

"error":true,

"code":404,

"errorNum":404,

"errorMessage":"nomatch"

}

ReturnCodes

200:isreturnedwhenthequerywassuccessfullyexecuted.400:isreturnedifthebodydoesnotcontainavalidJSONrepresentationofaquery.Theresponsebodycontainsanerrordocument

Hash

289

inthiscase.404:isreturnedifthecollectionspecifiedbycollectionisunknown.Theresponsebodycontainsanerrordocumentinthiscase.

Examples

Ifamatchingdocumentwasfound


example<<EOF

{


"example":{

"i":1

}

}

EOF

HTTP/1.1200OK



showresponsebodyIfnodocumentwasfound


example<<EOF

{


"example":{

"l":1

}

}

EOF

HTTP/1.1404NotFound



showresponsebody

Hash

290

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":[

"a",

"b"

]

}

EOF

HTTP/1.1201Created



{

"deduplicate":true,

"fields":[

"a",

"b"

],



"sparse":false,

"type":"skiplist",

"unique":false,

"error":false,

Skiplist

291

"code":201

}

Example:Creatingasparseskiplistindex


{

"type":"skiplist",

"unique":false,

"sparse":true,

"fields":[

"a"

]

}

EOF

HTTP/1.1201Created



{

"deduplicate":true,

"fields":[

"a"

],



"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":[

"a",

"b"

]

}

EOF

HTTP/1.1201Created



Skiplist

292

showresponsebodyCreatingasparseskiplistindex



{

"type":"skiplist",

"unique":false,

"sparse":true,

"fields":[

"a"

]

}

EOF

HTTP/1.1201Created



showresponsebody

Skiplist

293

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":[

"a",

"b"

]

}

EOF

HTTP/1.1201Created



{

"deduplicate":true,

"fields":[

"a",

"b"

],



"sparse":false,


"unique":false,

"error":false,

"code":201

Persistent

294

}

Example:Creatingasparsepersistentindex


{


"unique":false,

"sparse":true,

"fields":[

"a"

]

}

EOF

HTTP/1.1201Created



{

"deduplicate":true,

"fields":[

"a"

],



"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":[

"a",

"b"

]

}

EOF

HTTP/1.1201Created



Persistent

295

showresponsebodyCreatingasparsepersistentindex



{


"unique":false,

"sparse":true,

"fields":[

"a"

]

}

EOF

HTTP/1.1201Created



showresponsebody

Persistent

296

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":[

"b"

]

}

EOF

HTTP/1.1201Created



{

"constraint":false,

"fields":[

"b"

],

"geoJson":false,


"ignoreNull":true,


"sparse":true,

"type":"geo1",

"unique":false,

"error":false,

"code":201

}

Geo

297

http://geojson.org/geojson-spec.html#positions

Example:Creatingageoindexwithlatitudeandlongitudeattributes


{

"type":"geo",

"fields":[

"e",

"f"

]

}

EOF

HTTP/1.1201Created



{

"constraint":false,

"fields":[

"e",

"f"

],


"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":[

"b"

]

}

EOF

HTTP/1.1201Created



showresponsebodyCreatingageoindexwithlatitudeandlongitudeattributes



Geo

298

{

"type":"geo",

"fields":[

"e",

"f"

]

}

EOF

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

}

Geo

299

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12441",


"_rev":"_WQ47fgq--D",

"name":"Name/0.002/",

"loc":[

0.002,

0

]

},

{

"_key":"12435",


"_rev":"_WQ47fgq--_",

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

"loc":[

-0.002,

0

]

}

],

"hasMore":false,

"count":2,

"error":false,

"code":201

}



{


"latitude":0,

"longitude":0,

"skip":1,

"limit":3,


}

EOF

HTTP/1.1201Created



{

"result":[

{

"distance":222.38985328911744,


"_key":"12486",

"_rev":"_WQ47fhq--D",

"loc":[

-0.002,

0

],

"name":"Name/-0.002/"

},

{

"distance":222.38985328911744,


"_key":"12492",

"_rev":"_WQ47fhq--H",

Geo

300

"loc":[

0.002,

0

],


},

{

"distance":444.779706578235,


"_key":"12483",

"_rev":"_WQ47fhq--B",

"loc":[

-0.004,

0

],

"name":"Name/-0.004/"

}

],

"hasMore":false,

"count":3,

"error":false,

"code":201

}

ReturnCodes


Examples

Withoutdistance


{


"latitude":0,

"longitude":0,

"skip":1,

"limit":2

}

EOF

HTTP/1.1201Created





{


"latitude":0,

"longitude":0,

"skip":1,

"limit":3,


}

EOF

Geo

301

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

}

EOF

HTTP/1.1201Created



{

"result":[

{

"_key":"12854",


Geo

302

"_rev":"_WQ47foi--_",

"name":"Name/0.002/",

"loc":[

0.002,

0

]

},

{

"_key":"12848",


"_rev":"_WQ47foe--H",

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

"loc":[

-0.002,

0

]

}

],

"hasMore":false,

"count":2,

"error":false,

"code":201

}



{


"latitude":0,

"longitude":0,

"skip":1,

"limit":3,


"radius":300

}

EOF

HTTP/1.1201Created



{

"result":[

{

"distance":222.38985328911744,


"_key":"12899",

"_rev":"_WQ47fpW--B",

"loc":[

-0.002,

0

],

"name":"Name/-0.002/"

},

{

"distance":222.38985328911744,


"_key":"12905",

"_rev":"_WQ47fpW--F",

"loc":[

0.002,

0

],


},

{

"distance":444.779706578235,


"_key":"12896",

Geo

303

"_rev":"_WQ47fpW--_",

"loc":[

-0.004,

0

],

"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

}

EOF

HTTP/1.1201Created





{


"latitude":0,

"longitude":0,

"skip":1,

"limit":3,


"radius":300

}

EOF

HTTP/1.1201Created



Geo

304

showresponsebody

Geo

305

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"

]

}

EOF

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

306

Creatingafulltextindex



{

"type":"fulltext",

"fields":[

"text"

]

}

EOF

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"

}

EOF

HTTP/1.1201Created



Fulltext

307

{

"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

<<EOF

{


"attribute":"text",

"query":"word"

}

EOF

HTTP/1.1201Created



showresponsebody

Fulltext

308

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

309



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();}"

}

EOF

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!';}"

}

EOF

HTTP/1.1200OK



{

"error":false,

"code":200,

"result":"worked!"

}

Example:Abortingatransactionduetoaninternalerror


{

"collections":{

"write":"products"

Transactions

310

},

"action":"function(){vardb=require('@arangodb').db;db.products.save({_key:'abc'});db.products.save({_key:'abc'});}

"

}

EOF

HTTP/1.1409Conflict



{

"error":true,

"errorMessage":"uniqueconstraintviolated-inindex0oftypeprimaryover[\"_key\"];conflictingkey:abc",

"code":409,

"errorNum":1210

}

Example:Abortingatransactionbyexplicitlythrowinganexception


{

"collections":{

"read":"products"

},

"action":"function(){throw'doh!';}"

}

EOF




{

"error":true,

"errorMessage":"transactionnotrunningoncommit",

"code":500,

"errorNum":1650

}

Example:Referringtoanon-existingcollection


{

"collections":{

"read":"products"

},

"action":"function(){returntrue;}"

}

EOF

HTTP/1.1404NotFound



{

"error":true,


"code":404,

"errorNum":1203

}

ReturnCodes

Transactions

311

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();}"

}

EOF

HTTP/1.1200OK



showresponsebodyExecutingatransactionusingmultiplecollections


{

"collections":{

"write":[

"products",

"materials"

]

},

"action":"function(){vardb=

require('@arangodb').db;db.products.save({});db.materials.save({});return'worked!';}"

}

EOF

HTTP/1.1200OK



showresponsebodyAbortingatransactionduetoaninternalerror


{

"collections":{

"write":"products"

},

"action":"function(){vardb=require('@arangodb').db;db.products.save({_key:

'abc'});db.products.save({_key:'abc'});}"

}

Transactions

312

EOF

HTTP/1.1409Conflict



showresponsebodyAbortingatransactionbyexplicitlythrowinganexception


{

"collections":{

"read":"products"

},

"action":"function(){throw'doh!';}"

}

EOF




showresponsebodyReferringtoanon-existingcollection


{

"collections":{

"read":"products"

},

"action":"function(){returntrue;}"

}

EOF

HTTP/1.1404NotFound



showresponsebody

Transactions

313

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

314

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

315

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

316

"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

317

"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

318

},

"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

319

],

"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

320

"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

321

"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":[

"a",

"b"

],

"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

322

],


"unique":false,

"sparse":false,

"deduplicate":true

},

{

"id":"12024",

"type":"skiplist",

"fields":[

"a",

"b"

],

"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":[

"a"

],

"unique":false,

"sparse":false,

"deduplicate":true

}

],

"parameters":{


"cid":"12026",

"count":0,

"deleted":false,

"doCompact":true,


"id":"12026",

"indexBuckets":8,

"indexes":[

{

ReplicationDump

323

"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":[

"a"

],

"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

324

],

"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

325

"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

326

"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

327

"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

328

}

],

"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

329


"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

330

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

331


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

332

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

333

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

334

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

335

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

336

"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

337

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

338

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

339

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

340

{\"_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

341

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

342

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

343

{



"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

344

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

345

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

346

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

347

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

}

EOF

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

348

}

EOF

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

349

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

350


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

351


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

352

"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

353

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

354

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

355


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"

}


356

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

357

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

358

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

200:

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

359

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

360

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

361

"httpConnections":1,

"connectionTime":{

"sum":0,

"count":0,

"counts":[

0,

0,

0,

0

]

},

"totalTime":{

"sum":12.890824556350708,

"count":4034,

"counts":[

3799,

145,

76,

10,

4,

0,

0

]

},

"requestTime":{

"sum":0.030986785888671875,

"count":4034,

"counts":[

4033,

1,

0,

0,

0,

0,

0

]

},

"queueTime":{

"sum":0.0002090930938720703,

"count":9,

"counts":[

9,

0,

0,

0,

0,

0,

0

]

},

"ioTime":{

"sum":12.859628677368164,

"count":4034,

"counts":[

3800,

144,

76,

10,

4,

0,

0

]

},

"bytesSent":{

"sum":1794760,

"count":4034,

"counts":[

304,

3392,

319,

19,

0,

0

]

},

"bytesReceived":{

Monitoring

362

"sum":871054,

"count":4034,

"counts":[

3727,

307,

0,

0,

0,

0

]

}

},

"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

363

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

364

{

"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":[

0.01,

0.05,

0.1,

0.2,

0.5,

1

],

"units":"seconds"

},

{

"group":"client",

"identifier":"requestTime",

"name":"RequestTime",

"description":"Requesttimeneededtoanswerarequest.",


"cuts":[

Monitoring

365

0.01,

0.05,

0.1,

0.2,

0.5,

1

],

"units":"seconds"

},

{

"group":"client",

"identifier":"queueTime",

"name":"QueueTime",

"description":"Queuetimeneededtoanswerarequest.",


"cuts":[

0.01,

0.05,

0.1,

0.2,

0.5,

1

],

"units":"seconds"

},

{

"group":"client",

"identifier":"bytesSent",

"name":"BytesSent",

"description":"Bytessentsforarequest.",


"cuts":[

250,

1000,

2000,

5000,

10000

],

"units":"bytes"

},

{

"group":"client",

"identifier":"bytesReceived",

"name":"BytesReceived",

"description":"Bytesreceivedsforarequest.",


"cuts":[

250,

1000,

2000,

5000,

10000

],

"units":"bytes"

},

{

"group":"client",

"identifier":"connectionTime",

"name":"ConnectionTime",

"description":"Totalconnectiontimeofaclient.",


"cuts":[

0.1,

1,

60

],

"units":"seconds"

},

{

"group":"http",

"identifier":"requestsTotal",

"name":"Totalrequests",

"description":"TotalnumberofHTTPrequests.",


"units":"number"

},

Monitoring

366

{

"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

367

"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

368

GET/_admin/clusterStatistics

QueryParameters

DBserver(required):

ReturnCodes

200:isreturnedwheneverythingwentwell.400:theparameterDBserverwasnotgivenorisnottheIDofaDBserver403:serverisnotacoordinator.

Monitoring

369

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

370

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

371

FoxxHTTPAPITheseroutesallowmanipulatingtheFoxxservicesinstalledinadatabase.

FormoreinformationonFoxxanditsJavaScriptAPIsseetheFoxxchapterofthemaindocumentation.

FoxxServices

372

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

373

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

374








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

375



QueryParameters

mount(required):Mountpathoftheinstalledservice.teardown(optional):Settotruetoruntheoldservice'steardownscript.setup(optional):Settofalsetonotrunthenewservice'ssetupscript.legacy(optional):Settotruetoinstallthenewservicein2.8legacycompatibilitymode.

ReturnCodes


Management

376

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

377

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

378

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

379

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

380

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

381

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"

}

EOF

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

382

{


"passwd":"secure"

}

EOF

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"

}

EOF

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

383

"grant":"rw"

}

EOF

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"

}

EOF

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

384

}

EOF

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

385

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

Listtheaccessibledatabasesforauser

GET/_api/user/{user}/database/

PathParameters

user(required):Thenameoftheuserforwhichyouwanttoquerythedatabases.

QueryParameters

full(optional):Returnthefullsetofaccesslevelsforalldatabasesandallcollections.

Fetchthelistofdatabasesavailabletothespecifieduser.YouneedAdministratefortheserveraccesslevelinordertoexecutethisRESTcall.

ThecallwillreturnaJSONobjectwiththeper-databaseaccessprivilegesforthespecifieduser.Theresultobjectwillcontainthedatabasesnamesasobjectkeys,andtheassociatedprivilegesforthedatabaseasvalues.

Incaseyouspecifiedfull,theresultwillcontainthepermissionsforthedatabasesaswellasthepermissionsforthecollections.

UserManagement

386

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

387

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

388

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

389

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"

}

EOF

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

<<EOF

{

"passwd":"secure"

}

EOF

HTTP/1.1200OK



showresponsebody

ModifyUser

Modifyattributesofanexistinguser

PATCH/_api/user/{user}

PathParameters


UserManagement

390


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"

}

EOF

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

<<EOF

{

"passwd":"secure"

}

EOF

HTTP/1.1200OK



showresponsebody

RemoveUser

deleteauserpermanently.

DELETE/_api/user/{user}

PathParameters

UserManagement

391


Removesanexistinguser,identifiedbyuser.YouneedAdministratefortheserveraccesslevelinordertoexecutethisRESTcall.

Example:

shell>curl-XDELETE--data-binary@---dump-http://localhost:8529/_api/user/userToDelete@myapp<<EOF

{

}

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

{

}

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

392

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

393

{

"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

394

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);",


}

]

Tasks

395

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);",


Tasks

396

}

]

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


Tasks

397


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

}

EOF

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

Tasks

398

ReturnCodes

400:Ifthepostbodyisnotaccurate,aHTTP400isreturned.

Examples

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

{



"params":{

"foo":"bar",

"bar":"foo"

},

"period":2

}

EOF

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

}

EOF

HTTP/1.1200OK



{

Tasks

399

"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

<<EOF

{

"id":"SampleTask",



"params":{

"foo":"bar",

"bar":"foo"

},

"period":2

}

EOF

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,

Tasks

400

"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

}

Tasks

401

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

402

[{results:[1]}]

Andthesubsequentreadoperation

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/"]]'

[

{

"a":{

"b":{

"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"]]'

[

{

"a":{

"b":{

"c":[1,2,3]

}

}

}

]

And

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/c"]]'

[

{

"a":{

"b":{

"c":[1,2,3]

}

}

}

]

Notethattheaboveresultsareidentical,meaningthatresultsobtainedfromtheagencyarealwaysreturnwithfullpath.

Thesecondouterarraybracketsinreadoperationscorrespondtotransactions,meaningthattheresultisguaranteedtohavebeenacquiredwithoutawritetransactioninbetween:

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/e"],["/d","/a/b"]]'

Agency

403

[

{

"a":{

"e":12

}

},

{

"a":{

"b":{

"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"]]'

[

{

"a":{

"b":{}

}

}

]

Theresultreturnsthecrosssectionoftherequestedpathandthekey-value-storecontents."/a/b"exists,butthereisnokey"/a/b/d".Thusthefollowingtransactionwillyield:

curl-Lhttp://$SERVER:$PORT/_api/agency/read-d'[["/a/b/d","/d"]]'

[

{

"a":{

"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

404

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

405

Additionalrule:Ifnoneof"new"and"op"issetorthevalueisnotevenanobject,thenthisistobeinterpretedasifitwere

{"op":"set","new":<VALUE>}

whichamountstosettingthevaluewithnoprecondition.

Examples:

{"/a":{"op":"set","new":12}}

setsthevalueofthekey"/a"to12.Thesamecouldhavebeenachievedby

{"/a":12}

orby

{"/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

406

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

407

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":{


408

"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




409

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


410

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


411

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

}

EOF

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



412


{

"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


413


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.


414

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...